Select
updatedLooks like an input. It's a trap! A list of options behind a trigger that looks like an Input.
Open Props in the corner of the example to try variant, size and disabled.
The list opens at the trigger's size, so an xl trigger opens xl options. Want a different list? Give SelectContent its own size; it wins.
Installation
Usage
<script setup lang="ts">
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
const fruit = ref<string>()
</script>
<template>
<Select v-model="fruit">
<SelectTrigger aria-label="Fruit">
<SelectValue placeholder="Select a fruit" />
</SelectTrigger>
<SelectContent>
<SelectItem value="apple">Apple</SelectItem>
<SelectItem value="banana">Banana</SelectItem>
</SelectContent>
</Select>
</template>
The trigger has Input's variants and sizes, so it lines up with inputs in a form.
Start typing, and the list jumps to the matching option.
A long list shows the browser's own thin scrollbar, with no arrows above and below it. Want the arrows back, or a Scroll Area? That is your choice, and SelectContent is yours: put SelectScrollUpButton and SelectScrollDownButton on either side of its viewport, or wrap the slot in a ScrollArea. Hiding the scrollbar again takes an important class, because the kit shows it with one over Reka's own style: [&_[data-slot=select-viewport]]:[scrollbar-width:none]! on SelectContent.
While the list is open, a click outside only closes it, and nothing underneath gets clicked. More on overlays.
Inside a Field, it works as usual.
Examples
Groups
Put options in a SelectGroup with a SelectLabel as its heading. SelectSeparator draws a line between groups.
Too many options? The list scrolls. Cap its height with a max-h-* class on SelectContent.
Position
By default the list opens below the trigger, or above it when there is no room. With position="item-aligned" it opens over the trigger with the selected option exactly where the trigger's text is, as a native select does on macOS.
Icons
The trigger repeats the selected option's text, not its markup. To show an icon in the trigger too, fill SelectValue yourself from the selected value.
Field
A select in a required field gets aria-required, and when the field is invalid, aria-invalid and a --destructive border. Give the select a name to submit its value with the form through a hidden native select. Press Invite without choosing a role.
API Reference
Every part accepts class, merged over its base classes.
Select
| Prop | Default | Type and description |
|---|---|---|
| open | — | booleanWhether it is open, bound with |
| defaultOpen | — | booleanWhether it starts open when |
| defaultValue | — | AcceptableValue | AcceptableValue[]The starting value when |
| modelValue | — | AcceptableValue | AcceptableValue[]The selected value, or an array with |
| nullableValue | — | stringThe value that means nothing is selected. Choosing it shows the placeholder. |
| by | — | string | ((a: AcceptableValue, b: AcceptableValue) => boolean)Compares object values by this key, or with this function, instead of by reference. |
| dir | — | DirectionReading direction. Mirrors the layout and arrow keys in |
| multiple | — | booleanLets several options be selected. The trigger shows them joined by commas. |
| autocomplete | — | stringThe |
| disabled | — | booleanDisables the select. Also set by a disabled field. |
| name | — | stringSubmits the value with its form under this name through a hidden native select. |
| required | — | booleanMarks the select required. Also set by a required field. |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: AcceptableValue]Fires when the value changes. |
| update:open | [value: boolean]Fires when it opens or closes. |
| Slot | Scope and description |
|---|---|
| default | { modelValue: string | number | bigint | Record<string, any> | (string | number | bigint | Record<string, any> | null)[] | null | undefined; open: boolean; }The trigger and the content. |
SelectTrigger
| Prop | Default | Type and description |
|---|---|---|
| disabled | — | booleanDisables the trigger. A disabled field or select sets it too. |
| reference | — | ReferenceElementA virtual element to position the content against instead of the trigger. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| id | — | stringOverrides the |
| variant | — | "outline" | "soft" | "filled" | "ghost" | "subtle" | nullThe same five variants as the input. |
| size | "md" | SelectSizeHeight, matching the input sizes of the same name. The list opens at the same size unless |
| Slot | Scope and description |
|---|---|
| default | {}A |
SelectValue
| Prop | Default | Type and description |
|---|---|---|
| placeholder | — | stringText shown while nothing is selected. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | { selectedLabel: string[]; modelValue: AcceptableValue | AcceptableValue[] | undefined; }Custom content for the selected value, in place of the option's text. Receives |
SelectContent
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the panel mounted while closed, for animating it with a JavaScript library. |
| position | "popper" | "popper" | "item-aligned"
|
| bodyLock | — | booleanStops the page from scrolling while the list is open. |
| loop | — | booleanWraps arrow-key navigation from the last option to the first and back. Needs |
| memoDependencies | — | unknown[]Values that should re-run the position update when they change. |
| side | — | "top" | "right" | "bottom" | "left"The side of the trigger to open on. Flips to the other side when there is no room, unless |
| sideOffset | 4 | numberDistance in pixels from the trigger. |
| sideFlip | — | booleanFlips to the opposite side when the preferred one would overflow. |
| align | — | "start" | "center" | "end"Alignment against the trigger along the chosen side. |
| alignOffset | — | numberOffset in pixels from the |
| alignFlip | — | booleanFlips the alignment when it would overflow. |
| avoidCollisions | — | booleanKeeps the panel inside the collision boundary by flipping and shifting it. |
| collisionBoundary | — | Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default. |
| collisionPadding | — | number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start. |
| arrowPadding | — | numberPadding between an arrow and the panel's corners. |
| hideShiftedArrow | — | booleanHides an arrow when the panel is shifted so far that the arrow would not point at the trigger. |
| sticky | — | "partial" | "always"
|
| hideWhenDetached | — | booleanHides the panel when the trigger is scrolled out of view. |
| positionStrategy | — | "absolute" | "fixed"The CSS position used to place the panel. |
| updatePositionStrategy | — | "always" | "optimized"
|
| disableUpdateOnLayoutShift | — | booleanStops recomputing the position when the layout shifts. |
| prioritizePosition | — | booleanKeeps the preferred side and alignment and lets the panel overflow instead of flipping. |
| reference | — | ReferenceElementA virtual element to position against instead of the trigger. |
| dir | — | DirectionReading direction. Mirrors the layout and arrow keys in |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| disableOutsidePointerEvents | true | booleanMakes the list modal. On by default; turn it off to let outside clicks reach the page. |
| size | — | SelectSizeItem height, padding and text, |
| Event | Payload and description |
|---|---|
| closeAutoFocus | [event: Event]Fires when focus returns to the trigger on close. Call |
| escapeKeyDown | [event: KeyboardEvent]Fires on Escape. Call |
| pointerDownOutside | [event: PointerDownOutsideEvent]Fires on a pointer press outside. Call |
| Slot | Scope and description |
|---|---|
| default | {}The items, groups, labels and separators. |
SelectItem
| Prop | Default | Type and description |
|---|---|---|
| value* | — | AcceptableValueThe value this option puts in |
| disabled | — | booleanDisables the option: it is skipped by the keyboard and cannot be chosen. |
| textValue | — | stringText used for typeahead instead of the item's text content. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Event | Payload and description |
|---|---|
| select | [event: SelectEvent$1<AcceptableValue>]Fires when the option is chosen. Call |
| Slot | Scope and description |
|---|---|
| indicator-icon | {}The icon shown at the end of the selected option, a check by default. |
| default | {}The option's text, which the trigger repeats once it is selected. |
SelectGroup
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}A |
SelectItemText
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The option's text. |
SelectLabel
| Prop | Default | Type and description |
|---|---|---|
| for | — | stringSets the |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The group's name. |
SelectScrollDownButton
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The icon, a chevron by default. |
SelectScrollUpButton
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The icon, a chevron by default. |
SelectSeparator
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
Props
- open
booleanWhether it is open, bound withv-model:open.- defaultOpen
booleanWhether it starts open whenv-model:openis not used.- defaultValue
AcceptableValue | AcceptableValue[]The starting value whenv-modelis not used.- modelValue
AcceptableValue | AcceptableValue[]The selected value, or an array withmultiple, bound withv-model.- nullableValue
stringThe value that means nothing is selected. Choosing it shows the placeholder.- by
string | ((a: AcceptableValue, b: AcceptableValue) => boolean)Compares object values by this key, or with this function, instead of by reference.- dir
DirectionReading direction. Mirrors the layout and arrow keys inrtl.- multiple
booleanLets several options be selected. The trigger shows them joined by commas.- autocomplete
stringTheautocompletehint for the hidden native select.- disabled
booleanDisables the select. Also set by a disabled field.- name
stringSubmits the value with its form under this name through a hidden native select.- required
booleanMarks the select required. Also set by a required field.
Emits
- update:modelValue
[value: AcceptableValue]Fires when the value changes.- update:open
[value: boolean]Fires when it opens or closes.
Slots
- default
{ modelValue: string | number | bigint | Record<string, any> | (string | number | bigint | Record<string, any> | null)[] | null | undefined; open: boolean; }The trigger and the content.
Props
- disabled
booleanDisables the trigger. A disabled field or select sets it too.- reference
ReferenceElementA virtual element to position the content against instead of the trigger.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- id
stringOverrides theidtaken from a surrounding field.- variant
"outline" | "soft" | "filled" | "ghost" | "subtle" | nullThe same five variants as the input.- size
"md" SelectSizeHeight, matching the input sizes of the same name. The list opens at the same size unlessSelectContentsets its own.
Slots
- default
{}ASelectValue, and anything else to show before the chevron.
Props
- placeholder
stringText shown while nothing is selected.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{ selectedLabel: string[]; modelValue: AcceptableValue | AcceptableValue[] | undefined; }Custom content for the selected value, in place of the option's text. ReceivesmodelValueandselectedLabel.
Props
- forceMount
booleanKeeps the panel mounted while closed, for animating it with a JavaScript library.- position
"popper" "popper" | "item-aligned"popperopens the list below or above the trigger.item-alignedopens it over the trigger with the selected option where the trigger's text is, as a native select does on macOS.- bodyLock
booleanStops the page from scrolling while the list is open.- loop
booleanWraps arrow-key navigation from the last option to the first and back. Needsreka-ui2.11 or later.- memoDependencies
unknown[]Values that should re-run the position update when they change.- side
"top" | "right" | "bottom" | "left"The side of the trigger to open on. Flips to the other side when there is no room, unlessavoidCollisionsis off.- sideOffset
4 numberDistance in pixels from the trigger.- sideFlip
booleanFlips to the opposite side when the preferred one would overflow.- align
"start" | "center" | "end"Alignment against the trigger along the chosen side.- alignOffset
numberOffset in pixels from thealignposition.- alignFlip
booleanFlips the alignment when it would overflow.- avoidCollisions
booleanKeeps the panel inside the collision boundary by flipping and shifting it.- collisionBoundary
Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default.- collisionPadding
number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start.- arrowPadding
numberPadding between an arrow and the panel's corners.- hideShiftedArrow
booleanHides an arrow when the panel is shifted so far that the arrow would not point at the trigger.- sticky
"partial" | "always"partialkeeps the panel attached to the trigger while scrolling;alwaysalso lets it detach from the trigger to stay in the boundary.- hideWhenDetached
booleanHides the panel when the trigger is scrolled out of view.- positionStrategy
"absolute" | "fixed"The CSS position used to place the panel.- updatePositionStrategy
"always" | "optimized"alwaysrecomputes the position on every animation frame instead of only on layout changes.- disableUpdateOnLayoutShift
booleanStops recomputing the position when the layout shifts.- prioritizePosition
booleanKeeps the preferred side and alignment and lets the panel overflow instead of flipping.- reference
ReferenceElementA virtual element to position against instead of the trigger.- dir
DirectionReading direction. Mirrors the layout and arrow keys inrtl.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- disableOutsidePointerEvents
true booleanMakes the list modal. On by default; turn it off to let outside clicks reach the page.- size
SelectSizeItem height, padding and text,xstoxlas on Menu. Left out, the list takes the trigger's size.
Emits
- closeAutoFocus
[event: Event]Fires when focus returns to the trigger on close. CallpreventDefault()to keep focus where it is.- escapeKeyDown
[event: KeyboardEvent]Fires on Escape. CallpreventDefault()to keep it open.- pointerDownOutside
[event: PointerDownOutsideEvent]Fires on a pointer press outside. CallpreventDefault()to keep it open.
Slots
- default
{}The items, groups, labels and separators.
Props
- value*
AcceptableValueThe value this option puts inv-model.- disabled
booleanDisables the option: it is skipped by the keyboard and cannot be chosen.- textValue
stringText used for typeahead instead of the item's text content.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Emits
- select
[event: SelectEvent$1<AcceptableValue>]Fires when the option is chosen. Callevent.preventDefault()to keep the list open without selecting it.
Slots
- indicator-icon
{}The icon shown at the end of the selected option, a check by default.- default
{}The option's text, which the trigger repeats once it is selected.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}ASelectLabeland the options in the group.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The option's text.
Props
- for
stringSets theforattribute, for when the label renders as a<label>withas.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The group's name.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The icon, a chevron by default.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The icon, a chevron by default.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| select-trigger | data-state, data-placeholder, data-disabled, data-variant, data-size | The button. data-placeholder is set while nothing is selected; data-variant and data-size are set even when left at their defaults. |
| select-value | — | The selected option's text, or the placeholder. |
| select-content | data-state, data-side, data-align, data-size | The list's panel. data-size is its own size, or else the trigger's. |
| select-scrim | — | The transparent layer under the open list that takes the first outside click. |
| select-viewport | — | The scrolling part of the list. |
| select-item | data-state, data-highlighted, data-disabled | One option. data-state is checked for the selected one. |
| select-item-indicator | — | The check at the end of the selected option. |
| select-label | — | A group's name. |
| select-separator | — | The line between groups. |