CSC Design System v4.0.1
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<c-select>

A value-selection field: a readonly field that opens a listbox of options — slotted `c-option` elements or an `items` array — and holds the picked value, emitting the value events that back `v-model`.

Usage

Options

Options are slotted c-option elements or an items array of { name, value } entries. A slotted option's label — the text shown in the closed field and, in multiple mode, in its tag — is its name attribute, else the text of a c-option-value inside it, else the option's whole text. Wrap the label in c-option-value when an option carries more than its label, such as a description; the rest of the option's markup still renders in the list row.

<c-option selected> sets the initial value of plain HTML: once, only while the value is empty, and silently — no value event, so a bound v-model does not learn it. With a bound value, initialise the model instead.

The row shows a copy of the option's markup, re-created from its HTML inside the list. A component nested in an option — a c-icon, say — is therefore configured through attributes, or props with an attribute form (strings, numbers, booleans); object props and event listeners on option content do not carry over. Page CSS does not reach the copy either: give the content a part and style it through the field, which forwards every part named inside its options:

<c-option value="ts">
  <div part="language">
    <c-option-value>TypeScript</c-option-value>
    <c-icon path="…"></c-icon>
  </div>
</c-option>
c-select::part(language) {
  display: flex;
  align-items: center;
  gap: 0.5rem;
}

Multiple selection

Set multiple to let the user pick several options. The value is then an array of the picked options' values in the order they were picked (an array of { name, value } items with return-object), and [] when nothing is picked. Arrays have no attribute form — bind value as a DOM property (v-model or :value="…" in Vue; the React wrapper and property assignment do this naturally). Picking an option toggles it and keeps the list open; clearable clears the whole selection. option-as-selection has no effect in this mode.

Each picked option shows as a tag inside the field, and the field grows as the tags wrap. A tag's close button removes that option; Backspace in the closed field removes the last one. Set max-tags to show only that many tags and fold the rest into a single "+N more" tag, or max-tags="0" to show no tags at all — the field then reads "N selected". Assistive technology always hears the full selection as the field's value.

Set select-all to pin a select-all row at the top of the list. Its checkbox shows whether none, some or all enabled options are selected; activating it selects every enabled option, or unselects them all when they already are. Disabled options are left alone, and the row only appears while there is something to select. Its label is texts.selectAll, a function receiving the number of listed options.

The row checkboxes recolour like c-checkbox's (::part(indicator), ::part(mark)), the select-all row is the select-all part, and the tags are stylable through the tags, tag and tag-root parts:

c-select::part(tag-root) {
  background: var(--c-primary-subtle);
}

Texts

Every built-in string — the clear and toggle button labels, a tag's remove label, the overflow and count texts, the select-all row's label — can be replaced for another language through the texts object, merged over the English defaults. Count and label texts are functions, so the object must be bound as a DOM property:

<c-select
  :texts="{
    more: (n) => `+${n} lisää`,
    remove: (label) => `Poista ${label}`,
  }"
  multiple
/>

To translate every select at once, set texts app-wide with applyDefaults({ 'c-select': { texts } }) (Customization → App-wide prop defaults); a per-instance texts still wins key by key.

Scrolling

The list shows items-per-page full rows (six by default) and then a half-visible row instead of a scrollbar: the cut row is the cue that more options follow, and the wheel, touch and arrow keys scroll as usual. Set items-per-page="0" to let the list grow to the space the viewport allows; it still ends on a half row when it overflows. To bring the native scrollbar back:

c-select::part(list) {
  scrollbar-width: auto;
}

Narrow viewports

On a viewport narrower than 760px the panel opens as a fullscreen panel instead of dropping under the field: a heading row with the field's label and a close button, then the options filling the rest of the screen — the field itself stays where it is in the page. The panel keeps covering the screen and the heading row stays in view while the on-screen keyboard is open; the close button and Escape both return focus to the field; the page behind the panel is inert until it closes, and the list has no half-row cut — the screen edge is the cue. The threshold is the viewport's width, never the field's, so a narrow field on a desktop keeps its anchored panel. The close button's label is the closePanel text, and the row's parts are heading-row, heading and close:

c-select::part(heading-row) {
  border-bottom-color: var(--c-primary);
}

Examples

Basic
Vue React Angular TypeScript
<template>
  <div>
    <c-select
      v-model="country"
      hint="The list opens on click or with the arrow keys"
      label="Country"
      placeholder="Choose a country"
      clearable
    >
      <c-option name="Finland" value="fi">Finland</c-option>

      <c-option name="Sweden" value="se">Sweden</c-option>

      <c-option name="Norway" value="no">Norway</c-option>

      <c-option name="Denmark" value="dk">Denmark</c-option>
    </c-select>

    <p>Value: {{ country ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const country = ref<null | string>(null);
</script>
Multiple
Vue React Angular TypeScript
<template>
  <div>
    <!-- In multiple mode the value is an array in pick order. Picked options
         show as tags inside the field; `max-tags` folds the rest into one
         "+N more" tag. Backspace in the closed field removes the last tag. -->
    <c-select
      v-model="countries"
      hint="Pick as many as you like"
      label="Countries"
      max-tags="3"
      clearable
      multiple
    >
      <c-option name="Finland" value="fi">Finland</c-option>

      <c-option name="Sweden" value="se">Sweden</c-option>

      <c-option name="Norway" value="no">Norway</c-option>

      <c-option name="Denmark" value="dk">Denmark</c-option>

      <c-option name="Iceland" value="is">Iceland</c-option>

      <c-option name="Estonia" value="ee">Estonia</c-option>
    </c-select>

    <p>Value: {{ countries.length ? countries.join(', ') : '[]' }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const countries = ref<string[]>(['fi', 'se']);
</script>
Select all
Vue React Angular TypeScript
<template>
  <div>
    <!-- `select-all` pins a row at the top of the list that picks every
         enabled option, or unpicks them all once they are all picked. Its
         checkbox reads none, some or all; the disabled option is left alone. -->
    <c-select
      v-model="countries"
      hint="Pick some, or all at once"
      label="Countries"
      max-tags="3"
      clearable
      multiple
      select-all
    >
      <c-option name="Finland" value="fi">Finland</c-option>

      <c-option name="Sweden" value="se">Sweden</c-option>

      <c-option name="Norway" value="no">Norway</c-option>

      <c-option name="Denmark" value="dk">Denmark</c-option>

      <c-option name="Iceland" value="is">Iceland</c-option>

      <c-option name="Faroe Islands" value="fo" disabled>
        Faroe Islands
      </c-option>
    </c-select>

    <p>Value: {{ countries.length ? countries.join(', ') : '[]' }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const countries = ref<string[]>(['fi']);
</script>
Small
Vue React Angular TypeScript
<template>
  <div>
    <c-select v-model="country" label="Country" size="small">
      <c-option name="Finland" value="fi">Finland</c-option>

      <c-option name="Sweden" value="se">Sweden</c-option>

      <c-option name="Norway" value="no">Norway</c-option>
    </c-select>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const country = ref<null | string>('fi');
</script>
Basic · c-option
Vue React Angular TypeScript
<template>
  <div>
    <c-select
      v-model="country"
      hint="Each c-option provides a name and a value"
      label="Country"
      placeholder="Choose a country"
      clearable
    >
      <c-option name="Finland" value="fi">Finland</c-option>

      <c-option name="Sweden" value="se">Sweden</c-option>

      <c-option name="Norway" value="no">Norway</c-option>

      <c-option name="Denmark" value="dk" disabled>Denmark</c-option>
    </c-select>

    <p>Value: {{ country ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const country = ref<null | string>(null);
</script>
Basic · c-option-value
Vue React Angular TypeScript
<template>
  <div>
    <!-- The label lives in c-option-value; the description after it renders
         in the row but is not part of the label, so the filter matches and
         the closed field shows only "TypeScript". While a query is typed the
         runs of the label equal to it are marked (`::part(match)`). -->
    <c-autocomplete
      v-model="language"
      hint="Only the c-option-value text is filtered, marked and used as the label"
      label="Programming language"
      placeholder="Start typing to search"
      clearable
    >
      <c-option value="js">
        <c-option-value>JavaScript</c-option-value>

        <small>Web pages and Node.js</small>
      </c-option>

      <c-option value="ts">
        <c-option-value>TypeScript</c-option-value>

        <small>JavaScript with static types</small>
      </c-option>

      <c-option value="py">
        <c-option-value>Python</c-option-value>

        <small>Scripting and data science</small>
      </c-option>

      <c-option value="rs">
        <c-option-value>Rust</c-option-value>

        <small>Systems programming</small>
      </c-option>
    </c-autocomplete>

    <p>Value: {{ language ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const language = ref<null | string>(null);
</script>

API reference

<c-select>

A value-selection field: a readonly field that opens a listbox of options — slotted `c-option` elements or an `items` array — and holds the picked value, emitting the value events that back `v-model`.

Properties

PropertyAttributeTypeDefaultDescription
clearableclearablebooleanfalse Make the selected value clearable
disableddisabledbooleanfalse Disable the input
errorMessageerror-messagestring'' Error message shown in place of the hint while the select is invalid
hideMessagehide-messagebooleanfalse app default Hide the message line — the hint and error messages under the field — and the room it keeps.
hinthintstring'' Hint text for the input
invalidinvalidbooleanfalse Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`.
items—CSelectItem[]() => [] Dropdown items (when not using <c-option> elements)
itemsPerPageitems-per-pagenumber6 app default Items per page before adding scroll
labellabelstring'' Element label
labelOnToplabel-on-topbooleanfalse app default Label on top of the input
loadingloadingbooleanfalse Show loading state
maxTagsmax-tagsnumber— In `multiple` mode, show at most this many selected-value tags and fold the rest into one "+N more" tag; `0` shows no tags and reads "N selected" instead; unset shows every tag
multiplemultiplebooleanfalse Allow selecting several options: rows toggle and the list stays open, `value` becomes an array of the selected values (items with `return-object`) in the order they were picked, and the picks show as tags inside the field. `option-as-selection` is ignored in this mode. Arrays have no attribute form — bind `value` as a DOM property
namenamestring'' The name the picked value submits under in a native `<form>` — one entry per value with `multiple`
optionAsSelectionoption-as-selectionbooleanfalse Display the option as selection (only with <c-option> elements)
placeholderplaceholderstring'' Placeholder text
requiredrequiredbooleanfalse Set the select as required
returnObjectreturn-objectbooleanfalse Return object instead of value
selectAllselect-allbooleanfalse In `multiple` mode, pin a select-all row at the top of the list. Its checkbox shows whether none, some or all enabled options are selected; activating it selects every enabled option — or, when all are selected, unselects them. Ignored in single mode
shadowshadowbooleanfalse app default Shadow variant
sizesizeCFieldSize'default' app default Field height: the 52px default (the shared control height) or the 36px `small` box
texts—CSelectTexts{} app default UI text overrides (i18n), merged over the English defaults. Objects have no attribute form — bind as a DOM property (`:texts.prop` in Vue)
valuevalueCSelectValuenull Selected value: the option's value, or the whole item with `return-object`; an array of them in `multiple` mode
hideDetails deprecated hide-detailsbooleanfalse app default Deprecated. Use `hide-message`. Hide the hint and error messages

app default marks a prop you can set for every instance at once with applyDefaults() — an explicit attribute or property on an instance still wins.

Events

EventDetailDescription
changeCSelectValueFired when the selection changes (an option is picked or the value is cleared), carrying the new value — the option's value, or the whole `{ name, value }` item when `return-object` is set; `null` when cleared. In `multiple` mode the whole array of picked values, in pick order (`[]` when cleared).
inputvoidNative bubbling input event dispatched alongside every value change so a plain `v-model` stays in sync. Carries no detail.
update:valueCSelectValueFired alongside `change` with the same detail — the `v-model` contract.

Methods

MethodSignatureDescription
focus(options?: FocusOptions): voidFocus its combobox, as `focus()` does on a native control: the element renders no box of its own to take it.

Slots

SlotDescription
defaultThe `c-option` elements the list is built from, as an alternative to `items` (never rendered in place)
preContent inside the field, before the value, such as an icon
postContent inside the field, after its own controls (the chevron, clear button or loading spinner)

CSS parts

Style from outside with c-select::part(name) — parts are the library's only styling customization API.

PartDescription
panelThe positioned dialog holding the field and the list, as on the other value fields
cardThe same dialog as the painted surface: background, radius and shadow, as on the other value fields
heading-rowThe top row of the fullscreen panel (narrow viewports): the field label as heading and the close button
headingThe field label naming the fullscreen panel
closeThe close button of the fullscreen panel
listThe scrolling listbox of options
optionOne option row in the list. Any `part` attribute set on content inside a slotted `<c-option>` is exported too, so `c-select::part(<name>)` reaches the consumer's own option markup
select-allThe pinned select-all row at the top of the list (`multiple` mode with `select-all`); carries the same indicator / mark parts as an option row
indicatorThe decorative checkbox box on an option row in `multiple` mode; border, fill and glyph draw with `currentColor`, so `color` recolours them together (the c-checkbox recipe)
markThe check glyph inside a row indicator; draws with `currentColor`
tagsThe row of selected-value tags inside the field (`multiple` mode)
tagOne selected-value tag: the `c-tag` host, including the overflow tag
tag-rootThe pill box inside each tag (the `c-tag` `root` part), for colours and borders
messageThe hint / error message area below the field (always reserved unless `hide-message`)

Types

Importable from the package root: import type { … } from '@cscfi/csc-ui'

CSelectTexts

UI texts of `c-select`, shallow-merged over the English defaults. Static labels are strings; count- or label-interpolated ones are functions.

export interface CSelectTexts {
  /** Accessible label of the clear button. */
  clearSelection?: string;

  /** Accessible label of the close button in the fullscreen panel (narrow viewports). */
  closePanel?: string;

  /**
   * Text of the overflow tag when `max-tags` folds the selection; receives the
   * number of hidden tags.
   */
  more?: (count: number) => string;

  /** Accessible label of a tag's remove button; receives the option label. */
  remove?: (label: string) => string;

  /**
   * Label of the select-all row; receives the number of enabled options
   * listed.
   */
  selectAll?: (count: number) => string;

  /**
   * Field text when `max-tags="0"` shows no tags; receives the selection
   * count.
   */
  selected?: (count: number) => string;

  /** Accessible label of the chevron button that opens and closes the list. */
  toggleOptions?: string;
}
CSelectValue

Selection value of `c-select`: the picked option's value — or the whole `{ name, value }` item with `return-object` — and `null` when nothing is selected. In `multiple` mode an array of them in the order they were picked, `[]` when empty.

export type CSelectValue =
  | (number | string)[]
  | CSelectItem
  | CSelectItem[]
  | null
  | number
  | string;
CFieldSize shared

Field height of the form controls built on `c-input`. `default` is the 44px field; `small` is the 36px field. Owned here because the value passes from the wrapping control (`c-select`) into `c-input`.

export type CFieldSize = 'default' | 'small';
CSelectItem shared

A selectable item for the value-selection components (`c-select`, `c-autocomplete`) when options are supplied via the `items` prop instead of slotted `<c-option>` elements.

export interface CSelectItem {
  /** Disable the item so it cannot be selected. */
  disabled?: boolean;

  /** The item's display label. */
  name: string;

  /** The value emitted via v-model when the item is selected. */
  value: number | string;
}

<c-option>

One option of a `c-select` or `c-autocomplete`: `value` is what the field reports when the option is picked, and the option's label is its `name`, else the text of a `c-option-value` inside it, else its whole text. `disabled` keeps it from being picked, and `selected` sets the field's initial value once, silently, while that value is empty — with a bound `v-model`, initialise the model instead.

Properties

PropertyAttributeTypeDefaultDescription
disableddisabledbooleanfalse Set option as disabled
namenamestring— Option name (display label fallback)
selectedselectedbooleanfalse Set option as selected
valuevaluenumber | string— Option value

Slots

SlotDescription
defaultThe option's content, rendered in the list row; wrap the label text in c-option-value when the option carries more than its label

<c-option-value>

The label region of a `c-option`: wraps the text that c-select and c-autocomplete use as the option's label — in the closed field, its tag and the autocomplete filter — so the option can carry a description or an icon beside its label, and the region in which c-autocomplete marks the runs equal to the query (`::part(match)`).

Slots

SlotDescription
defaultThe option's label: the text c-select and c-autocomplete use for the option in the closed field, its tag and the filter, and the region c-autocomplete marks query matches in