Select

SSelect is a dropdown list built on Reka UI: keyboard navigation, ARIA roles, positioning and a portal. Options are set with the options array, the value is bound with v-model.

Basic usage

<template>
  <SSelect
    v-model="city"
    :options="options"
    placeholder="Choose a city"
    aria-label="City"
  />
</template>

Searching the list (searchable)

The searchable prop turns the select into an autocomplete field: an input renders instead of the trigger, and the list narrows down to the typed query (keyboard navigation, the combobox/listbox/option roles). The empty-text prop sets the message shown when no option matches.

<script setup lang="ts">
import { ref } from 'vue'
const city = ref()
const cities = [
  { label: 'New York', value: 'nyc' },
  { label: 'Los Angeles', value: 'la' },
  { label: 'Chicago', value: 'chi' },
]
</script>

<template>
  <SSelect
    v-model="city"
    searchable
    placeholder="Start typing a city…"
    empty-text="City not found"
    aria-label="City"
    :options="cities"
  />
</template>

Multiple selection (multiple / use-tags)

The multiple prop enables selecting several options: v-model becomes a string[], and the selected labels are listed in the field separated by commas. The use-tags prop (implies multiple) displays the selection as STag chips with a remove button. Both modes also work with searchable.

<script setup lang="ts">
import { ref } from 'vue'
const picked = ref(['nyc', 'la'])
const cities = [
  { label: 'New York', value: 'nyc' },
  { label: 'Los Angeles', value: 'la' },
  { label: 'Chicago', value: 'chi' },
]
</script>

<template>
  <SSelect
    v-model="picked"
    multiple
    label="Cities (comma-separated)"
    :options="cities"
  />
  <SSelect
    v-model="picked"
    use-tags
    label="Cities (tags)"
    :options="cities"
  />
</template>

Icons and clearing

The icon prop draws a leading icon inside the field; an option has an icon field (an icon before the label); dropdown-icon changes the expand indicator, and clearable adds a clear button.

<script setup lang="ts">
import { ref } from 'vue'
const framework = ref('vue')
</script>

<template>
  <SSelect
    v-model="framework"
    icon="search"
    dropdown-icon="chevron-down"
    clearable
    aria-label="Framework"
    :options="[
      { label: 'Vue', value: 'vue', icon: 'circle-check' },
      { label: 'React', value: 'react', icon: 'circle-check' },
      { label: 'Svelte', value: 'svelte', icon: 'circle-check' },
    ]"
  />
</template>

prepend / append slots

The prepend and append slots put arbitrary content inside the field border (before/after the control), as in the other form fields.

<template>
  <SSelect
    v-model="framework"
    aria-label="Framework"
    :options="options"
  >
    <template #prepend>
      <SIcon
        icon="filter"
        :size="16"
      />
    </template>
  </SSelect>
</template>

Label, hint and error

SSelect is built on SFormField: label renders a label above the field, hint a hint below it, error an error message (the field is marked invalid), required adds the * marker, and invalid marks the field invalid explicitly.

<script setup lang="ts">
const cities = [
  { label: 'New York', value: 'nyc' },
  { label: 'Los Angeles', value: 'la' },
  { label: 'Chicago', value: 'chi' },
]
</script>

<template>
  <SSelect
    label="City"
    hint="Main office"
    placeholder="Choose a city"
    :options="cities"
  />
  <SSelect
    label="City"
    error="This field is required"
    required
    placeholder="Choose a city"
    :options="cities"
  />
  <SSelect
    label="City"
    invalid
    placeholder="Choose a city"
    :options="cities"
  />
</template>

States and clearing

disabled blocks the select. The clearable flag adds a button that clears the selection, and clearIcon sets a custom icon for that button.

<script setup lang="ts">
import { ref } from 'vue'
const framework = ref('vue')
</script>

<template>
  <SSelect
    label="Disabled"
    disabled
    placeholder="Unavailable"
    :options="cities"
  />
  <SSelect
    v-model="framework"
    clearable
    clear-icon="circle-x"
    aria-label="Framework"
    :options="frameworks"
  />
</template>

append slot

The append slot puts content inside the field border on the right (after the control) — the counterpart of prepend.

<template>
  <SSelect
    v-model="framework"
    aria-label="Framework"
    :options="frameworks"
  >
    <template #append>
      <SIcon
        icon="tag"
        :size="16"
      />
    </template>
  </SSelect>
</template>

Long list

The panel has a limited height and scrolls inside: the limit is the smaller of max-height (20rem by default) and the free space to the edge of the window. The prop takes either a number (pixels) or a string with any unit.

Both selects below have 999 options. On the left is the default limit, on the right a smaller custom one.

<template>
  <SSelect
    v-model="count"
    :options="options"
    label="Number of parcels"
  />
  <SSelect
    v-model="count"
    :options="options"
    :max-height="160"
    label="With a custom limit"
  />
</template>

With a hundred or more options, searchable mode turns on virtualization: only the visible rows are kept in the DOM, so opening the list does not freeze the tab. It is controlled by the virtualize prop (true/false is an explicit choice, a number is a custom threshold). Open the list below and look in the inspector: there are a couple dozen nodes, not a thousand.

<template>
  <SSelect
    v-model="count"
    :options="options"
    searchable
    :virtualize="50"
    label="Number of parcels"
  />
</template>

Virtualization is for searchable only

The regular dropdown list is built on the Select primitive, and Reka UI has no virtualizer for it. If there really are thousands of options, enable searchable: it also makes them actually findable.

Square corners

square removes the rounding from both the border and the dropdown panel — open both lists and compare. The prop can also be set globally, with one key for the whole app: see Shape.

<template>
  <SSelect
    v-model="city"
    :options="cities"
    label="square"
    square
  />
</template>

Width

The border takes the parent's width and shrinks with it — in a narrow grid column the select does not overflow its boundary. If you still need a minimum, set it with a variable:

.filters .s-select__control {
  --s-select-min-width: 12rem;
}

List vs. search suggestions

SSelect picks from a known set: searchable filters the same options by substring. When the options come from the server and change on every keystroke, use SAutocomplete — it does not filter the suggestions again and passes the query text out.

API

Props

Name	Type	Default	Description
options*	{ label: string; value: string; disabled?: boolean; icon?: string }[]	required	List of options.
size	"md" | "sm" | "lg"	"md"	Field size: sm (32px), md (40px), or lg (48px).
label	string	undefined	Field label (rendered via SFormField/SLabel).
floating-label	boolean	true	Floating label (Material notched outline): the label sits inside the frame and floats up on focus or when a value is selected. Enabled by default. Not applicable in use-tags mode (the frame grows), where a regular label stays on top.
hint	string	undefined	Hint below the field.
error	string	undefined	Error message. When set, the field is marked invalid.
invalid	boolean	false	Marks the field invalid explicitly (in addition to error).
square	boolean	undefined	Square corners: removes the field border rounding (rounded by default).
required	boolean	false	Required field: a * marker next to the label.
id	string	undefined	Trigger id. Generated (SSR-safe) when not set.
placeholder	string	undefined	Trigger placeholder text shown until a value is selected.
searchable	boolean	false	Enables filtering options by typing (combobox behavior): an input renders instead of the trigger, and the list narrows to the typed query.
multiple	boolean	false	Multiple selection. modelValue becomes string[]; the selected labels are listed separated by commas. Combines with searchable.
use-tags	boolean	false	Multiple selection as tags (implies multiple): the selected options render as STag chips with a remove button. modelValue is string[].
empty-text	string	undefined	Text shown when nothing matches (searchable only; taken from the locale dictionary by default).
clear-label	string	undefined	Accessible name of the clear button (taken from the locale dictionary by default).
show-options-label	string	undefined	Accessible name of the list toggle button with searchable (taken from the locale dictionary by default).
icon	string	undefined	Leading icon inside the field (a registry name or a raw path), drawn on the left.
aria-label	string	undefined	Accessible name of the trigger (when there is no visible label).
disabled	boolean	undefined	Disables the select.
dropdown-icon	string	"chevron-down"	Registry name or raw path of the dropdown indicator icon.
clearable	boolean	false	Shows a clear button that resets the selection; visible when a value is selected.
clear-icon	string	"x"	Registry name or raw path of the clear button icon.
max-height	string | number	undefined	Maximum height of the dropdown list (20rem by default). A number means pixels. The panel also never grows past the space left to the window edge; the smaller of the two wins.
virtualize	number | false | true	undefined	Virtualizes a long list: only visible rows stay in the DOM. true means always, a number is the option count threshold, false means never. Enabled from 100 options by default. Works only with searchable: Reka has no suitable primitive for a dropdown without search, so enable searchable for thousands of options.
flat	boolean	undefined	Removes the shadow. Overridden by the elevation prop when it is set.
elevation	0 | 1 | 2 | 3 | 4 | 5	undefined	Shadow level 0–5 (scale); 0 means no shadow. Overrides flat.
model-value	string | string[]	undefined	Selection. Single: the option value (string); with multiple/use-tags: an array of value (string[]). Two-way binding via v-model.

Events

Name	Signature	Description
update:modelValue	( value: | string | string[] | undefined ) => void	Emitted when modelValue changes. Used for two-way binding (v-model).

Slots

Name	Description
prepend	Content at the start of the field, inside the frame (icon, button).
append	Content at the end of the field, inside the frame (icon, button).