Combobox
newCtrl+F for your dropdown. A text input that filters a list of options as you type.
Open Props in the corner of the example to try variant and size. The frame takes the input's height for each size, from 28px at xs to 48px at xl, so a combobox lines up with inputs and selects of the same size. The list opens at the anchor's size; size on ComboboxList overrides it. Behind a button, the anchor can't see the button's size: set size on ComboboxAnchor (or on the list) to match it.
The five text control variants, the same as on Input.
Installation
Usage
<script setup lang="ts">
import {
Combobox,
ComboboxAnchor,
ComboboxEmpty,
ComboboxInput,
ComboboxItem,
ComboboxList,
ComboboxTrigger,
ComboboxViewport,
} from '@/components/ui/combobox'
const frameworks = ['Astro', 'Next.js', 'Nuxt', 'Remix']
const framework = ref<string>()
</script>
<template>
<Combobox v-model="framework">
<ComboboxAnchor>
<ComboboxInput placeholder="Select a framework" aria-label="Framework" />
<ComboboxTrigger />
</ComboboxAnchor>
<ComboboxList>
<ComboboxViewport>
<ComboboxEmpty>No framework found.</ComboboxEmpty>
<ComboboxItem v-for="item in frameworks" :key="item" :value="item">{{ item }}</ComboboxItem>
</ComboboxViewport>
</ComboboxList>
</Combobox>
</template>
ComboboxAnchor: the frame, same as Input; the list opens at its widthComboboxInput: the text boxComboboxTrigger: the chevron; addComboboxCancelif you want a clear buttonComboboxList,ComboboxViewport: the panel and its scrolling options, styled like Select, with the browser's thin scrollbar ([scrollbar-width:none]!onComboboxViewporthides it)ComboboxEmpty: shows when nothing matches
Typing filters the options, ignoring case and accents. Using objects as values? Pass display-value to tell the input which text to show.
Unlike Select, the list isn't modal: the page stays clickable while it's open. More on overlays.
Set name, and the value submits with the form. Give the input an aria-label, or put it in a Field.
Examples
Behind a button
Want a button instead of an input? Wrap it in ComboboxAnchor and ComboboxTrigger with as-child, and it keeps its own look. Move ComboboxInput to the top of the list, and it gets focus as soon as the list opens.
Groups
ComboboxGroup gathers options under a ComboboxLabel, which also names the group for screen readers. A group hides while none of its options matches.
Multiple
With multiple, v-model is an array, a choice toggles the option, and the list stays open. Show the chosen values yourself, in the trigger as here or as tags.
Clear button
ComboboxCancel empties the text box, and with reset-model-value-on-clear the value too. It hides while the text box shows its placeholder.
In a field
Label, description and error come from the field. The label focuses the text box, required marks it, and invalid turns the frame destructive. Press Continue without choosing a country.
API Reference
Every part accepts class, merged over its base classes.
Combobox
| Prop | Default | Type and description |
|---|---|---|
| open | — | booleanWhether the list is open, bound with |
| defaultOpen | — | booleanWhether the list starts open when |
| resetSearchTermOnBlur | — | booleanPuts the chosen value's text back in the input when the list closes. On by default. |
| resetSearchTermOnSelect | — | booleanReplaces the typed text with the chosen value's text on selection. On by default. |
| openOnFocus | — | booleanOpens the list when the input gets focus. |
| openOnClick | — | booleanOpens the list when the input is clicked. |
| ignoreFilter | — | booleanTurns off the built-in filter, for filtering the options yourself, for example on a server. |
| resetModelValueOnClear | — | booleanMakes |
| unmountOnHide | — | booleanTurn off to keep the list mounted while closed, hidden with CSS, instead of rendering it again on every open. On by default. Needs |
| modelValue | — | T | T[]The chosen value, or an array with |
| defaultValue | — | T | T[]The starting value when |
| multiple | — | booleanLets several options be chosen. The list stays open after each one. |
| dir | — | DirectionReading direction. Mirrors the layout and arrow keys in |
| disabled | — | booleanDisables the input, the buttons and every option. Also set by a disabled field. |
| highlightOnHover | — | booleanMoves the highlight with the pointer. On by default. |
| loop | — | booleanWraps arrow-key navigation from the last option to the first and back. Needs |
| by | — | string | ((a: T, b: T) => boolean)Compares object values by this key, or with this function, instead of by reference. |
| asChild | — | booleanRender the single child instead of the root, merging the root's attributes onto it. |
| as | — | AsTag | ComponentThe element or component to render for the root. |
| name | — | stringSubmits the value with its form under this name, through a hidden input. |
| required | — | booleanMarks the hidden form input required. Also set by a required field. |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: T]Fires when the value changes. |
| highlight | [payload: { ref: HTMLElement; value: T; } | undefined]Fires when the highlighted option changes, with |
| update:open | [value: boolean]Fires when the list opens or closes. |
| Slot | Scope and description |
|---|---|
| default | { open: boolean; modelValue: T | T[]; }The anchor and the list. Receives |
ComboboxAnchor
| Prop | Default | Type and description |
|---|---|---|
| reference | — | ReferenceElementA virtual element to position the list against instead of the anchor. |
| asChild | — | booleanRender the single child instead of the frame. The child keeps its own look and becomes the element the list opens against. |
| as | — | AsTag | ComponentThe element or component to render. |
| variant | "outline" | "outline" | "soft" | "filled" | "ghost" | "subtle"The text control look, shared with |
| size | "md" | "md" | "xs" | "sm" | "lg" | "xl"Height, matching the input sizes of the same name. The list opens at the same size unless |
| Slot | Scope and description |
|---|---|
| default | {}A |
ComboboxInput
| Prop | Default | Type and description |
|---|---|---|
| displayValue | — | ((val: any) => string)Turns the chosen value into the text shown in the input, for object values. Not used with |
| modelValue | — | stringThe typed text, bound with |
| autoFocus | — | booleanFocuses the input when it mounts. |
| disabled | — | booleanDisables the input. A disabled combobox or field sets it too. |
| asChild | — | booleanRender the single child instead of the input, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| id | — | stringOverrides the |
| required | — | booleanMarks the input |
| Event | Payload and description |
|---|---|
| update:modelValue | [string]Fires as the text changes. |
ComboboxTrigger
| Prop | Default | Type and description |
|---|---|---|
| disabled | — | booleanDisables the button. A disabled combobox or field sets it too. |
| asChild | — | booleanRender the single child instead of the chevron button. The child keeps its own look and is reached with Tab. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The icon, by default a chevron that turns over while the list is open. With |
ComboboxCancel
| 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 cross by default. |
ComboboxList
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the list mounted while closed, for animating it with a JavaScript library. |
| position | "popper" | "popper" | "inline"
|
| bodyLock | — | booleanStops the page from scrolling while the list is open. |
| hideWhenEmpty | — | booleanHides the list while no option matches the typed text, instead of showing |
| memoDependencies | — | unknown[]Values that should re-run the position update when they change. |
| side | — | "top" | "right" | "bottom" | "left"The side of the anchor to open on. Flips to the other side when there is no room, unless |
| sideOffset | 4 | numberDistance in pixels from the anchor. |
| sideFlip | — | booleanFlips to the opposite side when the preferred one would overflow. |
| align | "start" | "start" | "center" | "end"Alignment against the anchor along the chosen side. |
| alignOffset | — | numberOffset in pixels from the |
| alignFlip | — | booleanFlips the alignment when it would overflow. |
| avoidCollisions | — | booleanKeeps the list 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 list's corners. |
| hideShiftedArrow | — | booleanHides an arrow when the list is shifted so far that the arrow would not point at the anchor. |
| sticky | — | "partial" | "always"
|
| hideWhenDetached | — | booleanHides the list when the anchor is scrolled out of view. |
| positionStrategy | — | "absolute" | "fixed"The CSS position used to place the list. |
| updatePositionStrategy | — | "always" | "optimized"
|
| disableUpdateOnLayoutShift | — | booleanStops recomputing the position when the layout shifts. |
| prioritizePosition | — | booleanKeeps the preferred side and alignment and lets the list overflow instead of flipping. |
| reference | — | ReferenceElementA virtual element to position against instead of the anchor. |
| dir | — | DirectionReading direction. Mirrors the placement 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 | — | booleanMakes the list modal, so an outside click only closes it. Off by default, so the page stays usable while it is open. |
| size | — | "xs" | "sm" | "md" | "lg" | "xl"Item height, padding and text, |
| Event | Payload and description |
|---|---|
| escapeKeyDown | [event: KeyboardEvent]Fires on Escape. Call |
| pointerDownOutside | [event: PointerDownOutsideEvent]Fires on a pointer press outside. Call |
| focusOutside | [event: FocusOutsideEvent]Fires when focus moves outside. Call |
| interactOutside | [event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. Call |
| Slot | Scope and description |
|---|---|
| default | {}A |
ComboboxItem
| Prop | Default | Type and description |
|---|---|---|
| value* | — | AcceptableValueThe value this option puts in |
| textValue | — | stringThe text the filter matches, for an option whose content is not plain text. |
| disabled | — | booleanDisables the option: it is skipped by the keyboard and cannot be chosen. |
| 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$3<AcceptableValue>]Fires when the option is chosen. Call |
| Slot | Scope and description |
|---|---|
| default | {}The option's content. |
| indicator-icon | {}The icon shown at the end of a chosen option, a check by default. |
ComboboxViewport
| Prop | Default | Type and description |
|---|---|---|
| nonce | — | stringThe |
| 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 options, groups, labels, separators and |
ComboboxEmpty
| 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 text shown while no option matches, “No options” by default. |
ComboboxGroup
| 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 |
ComboboxLabel
| 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. |
ComboboxSeparator
| 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 the list is open, bound withv-model:open.- defaultOpen
booleanWhether the list starts open whenv-model:openis not used.- resetSearchTermOnBlur
booleanPuts the chosen value's text back in the input when the list closes. On by default.- resetSearchTermOnSelect
booleanReplaces the typed text with the chosen value's text on selection. On by default.- openOnFocus
booleanOpens the list when the input gets focus.- openOnClick
booleanOpens the list when the input is clicked.- ignoreFilter
booleanTurns off the built-in filter, for filtering the options yourself, for example on a server.- resetModelValueOnClear
booleanMakesComboboxCancelclear the value too, tonullor[], not only the typed text.- unmountOnHide
booleanTurn off to keep the list mounted while closed, hidden with CSS, instead of rendering it again on every open. On by default. Needsreka-ui2.11 or later.- modelValue
T | T[]The chosen value, or an array withmultiple, bound withv-model.- defaultValue
T | T[]The starting value whenv-modelis not used.- multiple
booleanLets several options be chosen. The list stays open after each one.- dir
DirectionReading direction. Mirrors the layout and arrow keys inrtl.- disabled
booleanDisables the input, the buttons and every option. Also set by a disabled field.- highlightOnHover
booleanMoves the highlight with the pointer. On by default.- loop
booleanWraps arrow-key navigation from the last option to the first and back. Needsreka-ui2.11 or later.- by
string | ((a: T, b: T) => boolean)Compares object values by this key, or with this function, instead of by reference.- asChild
booleanRender the single child instead of the root, merging the root's attributes onto it.- as
AsTag | ComponentThe element or component to render for the root.- name
stringSubmits the value with its form under this name, through a hidden input.- required
booleanMarks the hidden form input required. Also set by a required field.
Emits
- update:modelValue
[value: T]Fires when the value changes.- highlight
[payload: { ref: HTMLElement; value: T; } | undefined]Fires when the highlighted option changes, with{ ref, value }, orundefinedwhen none is.- update:open
[value: boolean]Fires when the list opens or closes.
Slots
- default
{ open: boolean; modelValue: T | T[]; }The anchor and the list. ReceivesopenandmodelValue.
Props
- reference
ReferenceElementA virtual element to position the list against instead of the anchor.- asChild
booleanRender the single child instead of the frame. The child keeps its own look and becomes the element the list opens against.- as
AsTag | ComponentThe element or component to render.- variant
"outline" "outline" | "soft" | "filled" | "ghost" | "subtle"The text control look, shared withInput:outline,soft,filled,ghostorsubtle.- size
"md" "md" | "xs" | "sm" | "lg" | "xl"Height, matching the input sizes of the same name. The list opens at the same size unlessComboboxListsets its own; withas-childit sets only the list's.
Slots
- default
{}AComboboxInputfollowed by aComboboxCancelor aComboboxTrigger, or, withas-child, the button that opens the list.
Props
- displayValue
((val: any) => string)Turns the chosen value into the text shown in the input, for object values. Not used withmultiple.- modelValue
stringThe typed text, bound withv-model. Separate from the combobox's value.- autoFocus
booleanFocuses the input when it mounts.- disabled
booleanDisables the input. A disabled combobox or field sets it too.- asChild
booleanRender the single child instead of the input, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- id
stringOverrides theidtaken from a surrounding field.- required
booleanMarks the inputaria-required. A required field sets it too.
Emits
- update:modelValue
[string]Fires as the text changes.
Props
- disabled
booleanDisables the button. A disabled combobox or field sets it too.- asChild
booleanRender the single child instead of the chevron button. The child keeps its own look and is reached with Tab.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The icon, by default a chevron that turns over while the list is open. Withas-child, the button to render.
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 cross by default.
Props
- forceMount
booleanKeeps the list mounted while closed, for animating it with a JavaScript library.- position
"popper" "popper" | "inline"popperplaces the list against the anchor.inlineleaves the placement to your CSS.- bodyLock
booleanStops the page from scrolling while the list is open.- hideWhenEmpty
booleanHides the list while no option matches the typed text, instead of showingComboboxEmpty.- memoDependencies
unknown[]Values that should re-run the position update when they change.- side
"top" | "right" | "bottom" | "left"The side of the anchor to open on. Flips to the other side when there is no room, unlessavoidCollisionsis off.- sideOffset
4 numberDistance in pixels from the anchor.- sideFlip
booleanFlips to the opposite side when the preferred one would overflow.- align
"start" "start" | "center" | "end"Alignment against the anchor along the chosen side.startby default.- alignOffset
numberOffset in pixels from thealignposition.- alignFlip
booleanFlips the alignment when it would overflow.- avoidCollisions
booleanKeeps the list 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 list's corners.- hideShiftedArrow
booleanHides an arrow when the list is shifted so far that the arrow would not point at the anchor.- sticky
"partial" | "always"partialkeeps the list attached to the anchor while scrolling;alwaysalso lets it detach from the anchor to stay in the boundary.- hideWhenDetached
booleanHides the list when the anchor is scrolled out of view.- positionStrategy
"absolute" | "fixed"The CSS position used to place the list.- 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 list overflow instead of flipping.- reference
ReferenceElementA virtual element to position against instead of the anchor.- dir
DirectionReading direction. Mirrors the placement 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
booleanMakes the list modal, so an outside click only closes it. Off by default, so the page stays usable while it is open.- size
"xs" | "sm" | "md" | "lg" | "xl"Item height, padding and text,xstoxlas on Menu. Left out, the list takes the anchor's size.
Emits
- 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.- focusOutside
[event: FocusOutsideEvent]Fires when focus moves outside. CallpreventDefault()to keep it open.- interactOutside
[event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. CallpreventDefault()to keep it open.
Slots
- default
{}AComboboxViewportwith the options, and aComboboxInputabove it when the anchor is a button.
Props
- value*
AcceptableValueThe value this option puts inv-model.- textValue
stringThe text the filter matches, for an option whose content is not plain text.- disabled
booleanDisables the option: it is skipped by the keyboard and cannot be chosen.- 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$3<AcceptableValue>]Fires when the option is chosen. Callevent.preventDefault()to keep the list open without choosing it.
Slots
- default
{}The option's content.- indicator-icon
{}The icon shown at the end of a chosen option, a check by default.
Props
- nonce
stringThenoncefor the style tag Reka injects to hide the scrollbar (the kit shows it again), for a Content Security Policy. Inherited fromConfigProviderwhen omitted.- 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 options, groups, labels, separators andComboboxEmpty.
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 text shown while no option matches, “No options” 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
{}AComboboxLabeland the group's options. The group hides while none of them matches.
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.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| combobox | — | The root, holding the hidden form input. |
| combobox-anchor | data-variant, data-size | The frame the list opens against, or the button with as-child. With as-child it leaves the button's own data-variant and data-size alone. |
| combobox-input | data-disabled, aria-expanded, aria-invalid | The text box. |
| combobox-trigger | data-state, data-disabled | The chevron button, out of the tab order unless it renders a button with as-child. |
| combobox-cancel | — | The button that clears the text, out of the tab order. |
| combobox-list | data-state, data-side, data-align, data-empty, data-size | The list's panel. data-empty is set while no option matches; data-size is its own size, or else the anchor's. |
| combobox-viewport | — | The scrolling part of the list. |
| combobox-item | data-state, data-highlighted, data-disabled | One option. data-state is checked for a chosen one. |
| combobox-item-indicator | — | The check at the end of a chosen option. |
| combobox-group | — | A group of options, hidden while none matches. |
| combobox-label | — | A group's name. |
| combobox-separator | — | A line between options or groups. |
| combobox-empty | — | The text shown while no option matches. |
CSS variables
| Variable | Default | Description |
|---|---|---|
| --frame-radius | --radius-control-md at md | The frame's radius for its size. Set --control-radius to change every control at once. |
| --control-padding | 12px | Where the text starts from the frame's edge, and the chevron's distance from the other edge. |
Keyboard
| Key | Action |
|---|---|
| ArrowDown / ArrowUp | Opens the list, then moves the highlight through the options, skipping disabled ones. |
| Home / End | Highlights the first or last option. |
| Enter | Chooses the highlighted option. |
| Escape | Closes the list and puts the chosen value's text back in the input. |