<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
<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>
<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>
<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>
<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>
<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>
<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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
clearable | clearable | boolean | false | Make the selected value clearable |
disabled | disabled | boolean | false | Disable the input |
errorMessage | error-message | string | '' | Error message shown in place of the hint while the select is invalid |
hideMessage | hide-message | boolean | false app default | Hide the message line — the hint and error messages under the field — and the room it keeps. |
hint | hint | string | '' | Hint text for the input |
invalid | invalid | boolean | false | Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`. |
items | — | | () => [] | Dropdown items (when not using <c-option> elements) |
itemsPerPage | items-per-page | number | 6 app default | Items per page before adding scroll |
label | label | string | '' | Element label |
labelOnTop | label-on-top | boolean | false app default | Label on top of the input |
loading | loading | boolean | false | Show loading state |
maxTags | max-tags | number | — | 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 |
multiple | multiple | boolean | false | 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 |
name | name | string | '' | The name the picked value submits under in a native `<form>` — one entry per value with `multiple` |
optionAsSelection | option-as-selection | boolean | false | Display the option as selection (only with <c-option> elements) |
placeholder | placeholder | string | '' | Placeholder text |
required | required | boolean | false | Set the select as required |
returnObject | return-object | boolean | false | Return object instead of value |
selectAll | select-all | boolean | false | 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 |
shadow | shadow | boolean | false app default | Shadow variant |
size | size | CFieldSize | 'default' app default | Field height: the 52px default (the shared control height) or the 36px `small` box |
texts | — | | {} 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) |
value | value | | null | Selected value: the option's value, or the whole item with `return-object`; an array of them in `multiple` mode |
hideDetails deprecated | hide-details | boolean | false 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
| Event | Detail | Description |
|---|---|---|
change | CSelectValue | Fired 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). |
input | void | Native bubbling input event dispatched alongside every value change so a plain `v-model` stays in sync. Carries no detail. |
update:value | CSelectValue | Fired alongside `change` with the same detail — the `v-model` contract. |
Methods
| Method | Signature | Description |
|---|---|---|
focus | (options?: FocusOptions): void | Focus its combobox, as `focus()` does on a native control: the element renders no box of its own to take it. |
Slots
| Slot | Description |
|---|---|
default | The `c-option` elements the list is built from, as an alternative to `items` (never rendered in place) |
pre | Content inside the field, before the value, such as an icon |
post | Content 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.
| Part | Description |
|---|---|
panel | The positioned dialog holding the field and the list, as on the other value fields |
card | The same dialog as the painted surface: background, radius and shadow, as on the other value fields |
heading-row | The top row of the fullscreen panel (narrow viewports): the field label as heading and the close button |
heading | The field label naming the fullscreen panel |
close | The close button of the fullscreen panel |
list | The scrolling listbox of options |
option | One 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-all | The 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 |
indicator | The 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) |
mark | The check glyph inside a row indicator; draws with `currentColor` |
tags | The row of selected-value tags inside the field (`multiple` mode) |
tag | One selected-value tag: the `c-tag` host, including the overflow tag |
tag-root | The pill box inside each tag (the `c-tag` `root` part), for colours and borders |
message | The 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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Set option as disabled |
name | name | string | — | Option name (display label fallback) |
selected | selected | boolean | false | Set option as selected |
value | value | number | string | — | Option value |
Slots
| Slot | Description |
|---|---|
default | The 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
| Slot | Description |
|---|---|
default | The 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 |