Select

A button that opens a list of options to pick from.

Usage

Code
import { Select } from '@leverui/components';
Code
<Select.Root>
  <Select.HiddenSelect />
  <Select.Label />

  <Select.Control>
    <Select.Trigger>
      <Select.ValueText />
    </Select.Trigger>
    <Select.IndicatorGroup>
      <Select.Indicator />
      <Select.ClearTrigger />
    </Select.IndicatorGroup>
  </Select.Control>

  <Select.Positioner>
    <Select.Content>
      <Select.List>
        <Select.Item />

        <Select.ItemGroup>
          <Select.ItemGroupLabel />
          <Select.Item />
        </Select.ItemGroup>
      </Select.List>
    </Select.Content>
  </Select.Positioner>
</Select.Root>

Create the collection with Select.useListCollection. It holds the items and the value and label of each one.

Put the items inside Select.List. It has the listbox role and takes keyboard focus. Select.Content is the popup around the list. For a loading or error message, put Select.Status next to the list.

Examples

Sizes

Use the size prop to change the size of the select component.

Variants

Use the variant prop to change the appearance of the select component.

Color Palette

The Select component is designed to be neutral-colored by default for consistency across form elements. To apply a color palette, style the trigger and indicator components directly using the colorPalette token.

Option Group

Use the Select.ItemGroup component to group select options.

Controlled

Use the value and onValueChange props to control the select component.

Async Loading

Here's an example of how to populate the select collection from a remote source.

Hook Form

Here's an example of how to use the Select component in a form with a Solid signal holding its value.

Disabled

Use the disabled prop to disable the select component.

Invalid

Here's an example of how to compose the Select component with the Field component to display an error state.

Country is required

Multiple

Use the multiple prop to allow multiple selections.

Positioning

Use the positioning prop to control the underlying floating-ui options of the select component.

Clear Trigger

Render the Select.ClearTrigger component to show a clear button. Clicking the clear button will clear the selected value.

Overflow

When the options are too many, the options will overflow the container due to the maxHeight set.

Virtualized

For large collections, combine the Select with TanStack Virtual to render only the visible items and keep scrolling responsive. Its Solid adapter targets Solid 1, so the example uses a small Solid 2 binding over @tanstack/virtual-core.

Item Description

Here's an example of how to render a description for each item.

Open From Popover

Here's an example of how to use the Select within a Popover component.

Open From Dialog

To use the Select within a Dialog, you need to avoid portalling the Select.Positioner to the document's body.

Code
-<Portal>
  <Select.Positioner>
    <Select.Content>
      <Select.List>
        {/* ... */}
      </Select.List>
    </Select.Content>
  </Select.Positioner>
-</Portal>

If you have set scrollBehavior="inside" on the Dialog, you need to:

  • Set the select positioning to fixed to avoid the select from being clipped by the dialog.
  • Set hideWhenDetached to true to hide the select when the trigger is scrolled out of view.
Code
<Select.Root positioning={{ strategy: 'fixed', hideWhenDetached: true }}>
  {/* ... */}
</Select.Root>

Avatar Select

Here's an example of how to compose the Select and the Avatar.

Country Select

Here's an example of how to use the Select component to select a country.

Icon Button

Here's an example of how to trigger the select component with an IconButton.

Guides

Machine state and helpers

Control a Select with value and onValueChange. The callback's details.value is a string[]. defaultValue sets the first selection without controlling it. multiple allows more than one value. Disabled items stay visible but cannot be selected. disabled and readOnly on Root apply to the whole field.

ItemGroup and ItemGroupLabel group options. RootProvider takes a useSelect machine that you create outside the component. PropsProvider sets default props for the roots inside it. Context, ItemContext, useSelectContext, and useSelectItemContext give you the machine state for custom parts. The collection helpers live under Select: Select.createListCollection and Select.useListCollection.

Forms and validation

For native FormData, put HiddenSelect inside a Root that has a name. With a Solid form controller, pass its signal to value and copy details.value back into it in onValueChange. Set invalid when validation fails. Pass onInteractOutside to the controller's blur or touched handler, so the field state updates when someone leaves the popup.

Custom options

For items with their own shape, itemToString and itemToValue tell the collection each item's label and value. Avatars: use the member ID as the value and show the avatar and name. Countries: group by continent, show each flag, and submit the country code as the value.

An icon-only trigger needs an accessible name. Read Select.useSelectContext() and spread its getTriggerProps() onto your own square IconButton. Work out the icon from the selected value in the collection, so it updates with the selection.

Select inside overlays

In a Dialog or Popover, keep Select.Positioner inside the overlay's content. Do not portal it to the document body, so the listbox stays where the overlay holds focus. Keep HiddenSelect inside the named root, so native form values work.

Props

Root

PropDefaultTypeDescription
collection (required)—ListCollection<T>Items to choose from.
closeOnSelecttruebooleanClose after an item is selected.
compositetruebooleanUsed inside another composite widget, such as tabs or a combobox.
variantoutline'outline' | 'subtle' | 'ghost'Select style.
sizemd'xs' | 'sm' | 'md' | 'lg'Select size.
asdivNative tagHTML tag to render.
asChild—Solid render functionRender your own element with the root's props.
unstyled—booleanTurn off the default styles.
autoComplete—stringautocomplete attribute for the hidden select, such as "address-level1" for a state.
defaultHighlightedValue—stringItem highlighted when the select opens, when uncontrolled.
defaultOpen—booleanOpen at first, when uncontrolled.
defaultValue—string[]Values selected at first, when uncontrolled.
deselectable—booleanClear the value when the selected item is clicked. Single selection only.
disabled—booleanDisable the select.
form—stringForm the underlying select belongs to.
highlightedValue—stringValue of the highlighted item, when controlled.
id—stringUnique id of the state machine.
ids—Partial<{ root: string content: string control: string trigger: string clearTrigger: string label: string hiddenSelect: string positioner: string item: (id: string | number) => string itemGroup: (id: string | number) => string itemGroupLabel: (id: string | number) => string }>Ids of the elements in the select.
immediate—booleanApply a change to present at once, not on the next frame.
invalid—booleanMark the select invalid.
lazyMountfalsebooleanMount the popup content only when first opened.
loopFocusfalsebooleanWrap keyboard navigation at the first and last option.
multiple—booleanAllow selecting more than one item.
name—stringname attribute of the underlying select.
onExitComplete—VoidFunctionCalled when the closing animation ends.
onFocusOutside—(event: FocusOutsideEvent) => voidCalled when focus moves outside the select.
onHighlightChange—(details: HighlightChangeDetails<T>) => voidCalled when the highlighted item changes.
onInteractOutside—(event: InteractOutsideEvent) => voidCalled on an interaction outside the select.
onOpenChange—(details: OpenChangeDetails) => voidCalled when the popup opens or closes.
onPointerDownOutside—(event: PointerDownOutsideEvent) => voidCalled on a pointer press outside the select.
onSelect—(details: SelectionDetails) => voidCalled when an item is selected.
onValueChange—(details: ValueChangeDetails<T>) => voidCalled when the selected item changes.
open—booleanWhether the menu is open.
positioning—PositioningOptionsMenu placement options.
present—booleanWhether the popup is present, when controlled.
readOnly—booleanMake the select read-only.
required—booleanMake the select required.
scrollToIndexFn—(details: ScrollToIndexDetails) => voidScroll to a given index.
skipAnimationOnMountfalsebooleanSkip the animation when the popup first mounts.
translations—IntlTranslationsTranslated names for the accessible elements and their states.
unmountOnExitfalsebooleanUnmount the popup content when it closes.
value—string[]Values of the selected items, when controlled.

Customize with CSS

Import @leverui/components/styles.css once, before your own CSS. Built in: size="xs" | "sm" | "md" | "lg" and variant="outline" | "subtle" | "ghost", both responsive. The root and its parts have data-size and data-variant attributes, plus attributes for interaction states. The trigger fills its width by default. Pass positioning to place the popup differently.

Set the --leverui-select-* variables on :root, on an element that wraps a themed area, or on one component. Or style the .leverui-select__* classes. Every part takes class and style. unstyled turns off the default styles but keeps the behavior.

Neutral colors by default. To color a trigger with a palette, set colorPalette on Root, then use --leverui-colors-color-palette-muted, --leverui-colors-color-palette-subtle, and --leverui-colors-color-palette-fg in your own CSS or in the style of Trigger.

Explorer

Click a part name to highlight it in the preview.

Component Anatomy

Hover to highlight, click to select parts