Combobox

new

Ctrl+F for your dropdown. A text input that filters a list of options as you type.

Demo

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 width
  • ComboboxInput: the text box
  • ComboboxTrigger: the chevron; add ComboboxCancel if you want a clear button
  • ComboboxList, ComboboxViewport: the panel and its scrolling options, styled like Select, with the browser's thin scrollbar ([scrollbar-width:none]! on ComboboxViewport hides 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.

Behind a button

Groups

ComboboxGroup gathers options under a ComboboxLabel, which also names the group for screen readers. A group hides while none of its options matches.

Groups

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.

With multiple choice

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.

Clear button

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.

In a field

Where the invoice is sent.

API Reference

Every part accepts class, merged over its base classes.

Data attributes

data-slotAttributesDescription
combobox—The root, holding the hidden form input.
combobox-anchordata-variant, data-sizeThe 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-inputdata-disabled, aria-expanded, aria-invalidThe text box.
combobox-triggerdata-state, data-disabledThe 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-listdata-state, data-side, data-align, data-empty, data-sizeThe 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-itemdata-state, data-highlighted, data-disabledOne 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

VariableDefaultDescription
--frame-radius--radius-control-md at mdThe frame's radius for its size. Set --control-radius to change every control at once.
--control-padding12pxWhere the text starts from the frame's edge, and the chevron's distance from the other edge.

Keyboard

KeyAction
ArrowDown / ArrowUpOpens the list, then moves the highlight through the options, skipping disabled ones.
Home / EndHighlights the first or last option.
EnterChooses the highlighted option.
EscapeCloses the list and puts the chosen value's text back in the input.

Changelog

  1. registry 0.24.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  2. core 0.17.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  3. registry 0.22.0

    552297f — The text-control frame moves to its own lib item text-control; Select, Combobox, DatePicker and the other text controls import it from @/lib/text-control instead of @/ui/input.

    3d564c4 — A long Select or Combobox list shows the browser's thin scrollbar, as Menu does, instead of scrolling with no visible sign. Reka hides it with an unlayered style, so the viewports set [scrollbar-width:thin]!; hiding it again takes an important class too, such as [&_[data-slot=select-viewport]]:[scrollbar-width:none]! on SelectContent or [scrollbar-width:none]! on ComboboxViewport.

  4. registry 0.21.0

    6de5eb4 — The Select trigger's chevron and the Combobox chevron grow with size like every other control's icons (--control-icon-*, 14px at xs to 20px at xl), and the Select trigger's gap follows --control-gap-*; the Combobox clear button stays 2px smaller than the chevron. sm and md look as before.

  5. registry 0.15.0

    d09f26a — Pressable parts ripple on their own: Button, Toggle, ToggleGroupItem, Item as a link or a button, the calendar days, tabs, accordion, menubar and navigation menu triggers, the items of Menu, Menubar, Select, Combobox, Command, DrawerMenu, Listbox and Tree, and the clear buttons of TagsInput and Combobox. Each imports the directive from @/lib/ripple, so add brings the ripple item along and nothing needs registering. On menu, listbox and tree rows the wave replaces the pressed layer, as state-layer already did. Bind v-ripple="false" on a Button to turn one off, or set --kappa-ripple: none on :root to turn them all off.

  6. registry 0.13.0

    93e57a0 — Every size on the control scale is named xs to xl; default and the bare icon are gone. To move over:

    - Button: size="default" becomes size="md", or leave size out; size="icon" becomes size="icon-md". The full set is xs to xl and icon-xs to icon-xl. Toggle, ToggleGroup, ToggleGroupItem, the Toolbar parts, AlertDialogAction, AlertDialogCancel and ToastAction take the same names; Button, Toggle and ToggleGroup default to md, the Toolbar parts keep sm and ToastAction keeps xs. InputGroupButton keeps its own xs, sm, icon-xs and icon-sm, 24 and 32px to fit inside the group, xs by default. Pagination hands its md to Button as it is. Button, Toggle and ToggleGroupItem set data-variant, data-color and data-size even when you leave them at their defaults. - AlertDialogContent: size="default" becomes size="md", still the default; sm is unchanged. The size option of useConfirm's confirm, alert and prompt takes the same names. - Table and DataTable: density becomes size, data-density becomes data-size, and the TableDensity type is now TableSize. sm, md and lg keep their 36, 44 and 52px rows; xs (28px) and xl (60px) are new, and DataTable's virtual row estimates cover them. The cells' padding above and below the text is now --table-cell-py on the table: 8px as before, 3px at xs. At xs, DataTable's sort buttons and expand and group toggles shrink to fit the row. The table-density example is now table-sizes. - DrawerMenu: size takes xs to xl like Menu and reads the control scale, plus room for a thumb. sm, md and lg keep their 40, 48 and 56px rows, padding and icons; xs is 36px and xl 64px. Overriding a --control-* token on :root now resizes DrawerMenu rows as well. - Select and Combobox: the list opens at the trigger's or anchor's size instead of always at md, so <SelectTrigger size="xl"> opens an xl list. size on SelectContent or ComboboxList picks another. Behind an as-child button, set size on ComboboxAnchor to match the button. The Select list now sets its menu variables on SelectContent instead of its viewport, so a class such as [--menu-item-height:2.5rem] on SelectContent reaches the items. - Input, Textarea, InputFloating, SelectTrigger, ComboboxAnchor and Separator set data-size with the default filled in, and the anchor sets data-variant too. With as-child, the anchor leaves the button's own data-variant and data-size alone.

  7. registry 0.12.0

    c79028b — The control scale is now a set of tokens: --control-height-*, --control-padding-*, --control-icon-* and --control-gap-* for xs to xl, added to :root by the tokens item. Button, Input, InputFloating, Select, Combobox, InputNumber, TagsInput, PinInput, InputTime, InputGroup, Menu, Tabs, ColorPicker and Pagination read them, so overriding one on :root resizes every control of that size.

    Some sizes that strayed from the scale now follow it. Button icons are 20px at lg and xl instead of 16px, and so are the icons of Toggle, ToggleGroup, Toolbar and Pagination at those sizes. The gap between an icon and its label is 6, 8, 8, 10 and 12px from xs to xl, about half the icon, everywhere that has one: Button and the components built on it (where it was 4, 6, 8, 8 and 8px), Menu items and the Select, Combobox and Command lists (8, 10, 12, 12 and 12px), and Tabs triggers (6, 8, 8, 8 and 10px). Inset and checkbox or radio items move their labels with it, so they stay in line with items that have an icon. Everything else keeps its size.

  8. registry 0.11.0

    The text control frame of InputGroup, InputNumber, TagsInput and the Combobox anchor ignores what sits in an InputGroupAddon: a disabled checkbox's hidden form input no longer greys the frame or fades the addons, and the browser focusing it after a failed submit no longer lights the frame. A focused control that fails native validation shows the destructive edge again instead of the focus one.

  9. registry 0.10.0

    e03458c — The text control frame of InputGroup, InputNumber, TagsInput and the Combobox anchor reads focus, invalid and disabled from any input, textarea or role="spinbutton" inside it, not only from a direct child. An InputGroupAddon click focuses the first segment of a segmented control, and addons fade when any input inside the group is disabled.

  10. registry 0.9.0

    3724c06 — New Combobox: a text input that filters a list of options as you type, over Reka UI's Combobox. ComboboxAnchor is Input's frame with its variants and sizes and holds ComboboxInput, ComboboxCancel and the chevron ComboboxTrigger; with as-child the anchor and trigger become a button of your own and the input moves into the list. ComboboxList, ComboboxViewport, ComboboxItem, ComboboxGroup, ComboboxLabel, ComboboxSeparator and ComboboxEmpty take Select's list styles. Single or multiple choice, wired to a surrounding Field.