Select

updated

Looks like an input. It's a trap! A list of options behind a trigger that looks like an Input.

Demo

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.

Groups

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.

Item aligned

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.

Icons

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.

Field

Admins are added by the account owner.

API Reference

Every part accepts class, merged over its base classes.

Data attributes

data-slotAttributesDescription
select-triggerdata-state, data-placeholder, data-disabled, data-variant, data-sizeThe 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-contentdata-state, data-side, data-align, data-sizeThe 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-itemdata-state, data-highlighted, data-disabledOne 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.

Changelog

  1. registry 0.23.0

    bc6008b — Exits now use the decelerating curve, like entrances. Collapsible, Accordion, the overlay surfaces (Popover, Select, Menu, Tooltip), Drawer, Toast and InnerLoading used to close on --ease-emphasized-accelerate, which holds still for most of its duration and then snaps shut; closing on --ease-standard-decelerate starts at once and settles gently, so the same duration feels faster. The tokens themselves are unchanged.

  2. core 0.17.0

    0107e40 — The scrollbar's space is kept only while an overlay locks scrolling, as Base UI does, instead of on every page. @kappa-ui/core/tailwind.css no longer sets html { scrollbar-gutter: stable }, so a page too short to scroll no longer shows an empty strip along its edge on Windows. Dialog, Drawer, Select, Menu, Popover and DatePicker set scrollbar-gutter: stable on <html> while the page is locked and it would otherwise scroll, and remove it afterwards; a gutter your stylesheet already reserves is left alone. Keep ConfigProvider with :scroll-body="false". Want the old always-on gutter? Add html { scrollbar-gutter: stable; } to your stylesheet.

    bc6008b — Exits now use the decelerating curve, like entrances. Collapsible, Accordion, the overlay surfaces (Popover, Select, Menu, Tooltip), Drawer, Toast and InnerLoading used to close on --ease-emphasized-accelerate, which holds still for most of its duration and then snaps shut; closing on --ease-standard-decelerate starts at once and settles gently, so the same duration feels faster. The tokens themselves are unchanged.

  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.

    ad14b64 — SelectContent no longer renders SelectScrollUpButton and SelectScrollDownButton: a long list scrolls like any other instead of scrolling under the pointer as it hovers an arrow. Both parts stay exported, so a project that wants them puts them back around the viewport in its own SelectContent, or wraps the slot in a ScrollArea.

    e5495ef — size works the same way everywhere. Every component exports its size type (AlertSize, BadgeSize, CardSize, CheckboxSize, RadioSize, SwitchSize, EmptySize, InputFloatingSize, ItemSize, ListboxSize, SeparatorSize, SliderSize, StepperSize, TabsSize, TextareaSize, TimelineSize) and the props take it without null; Button-based parts take ButtonSize, Input TextControlSize, SelectTrigger SelectSize and Tree TreeSize. ToggleGroup and ToolbarToggleGroup carry data-size on the group as well. Table's row heights moved into tableSize, so a class on DataTable's ui.table overrides --table-row-h at every size, not only at md.

  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.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.