Select

A custom dropdown for picking one value from a list, from @clerk/headless. It is a headless primitive: it supplies value and open state, portalling, floating-ui positioning (with optional native-<select>-style item alignment), keyboard navigation with typeahead, and ARIA wiring, but ships no styles — you bring your own CSS by targeting the data-* attributes each part emits.

Example

The demo below is intentionally unstyled — it renders the raw primitive so you can see its behavior and ARIA wiring. Open it and pick an option (arrow keys, typeahead, and Enter all work); the trigger reflects the selected value.

Usage

import { Select } from '@clerk/headless/select';

<Select.Root>
  <Select.Trigger>
    <Select.Value placeholder='Choose a fruit…' />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup>
        <Select.Option value='apple'>Apple</Select.Option>
        <Select.Option value='banana'>Banana</Select.Option>
        <Select.Option
          value='cherry'
          disabled
        >
          Cherry
        </Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>;

Controlled

const [value, setValue] = useState('apple');

<Select.Root
  value={value}
  onValueChange={setValue}
>
  {/* trigger + portal */}
</Select.Root>;

Parts

All rendered parts accept a render prop for polymorphic rendering and standard HTML attributes for their default element. Select.Arrow accepts floating-ui FloatingArrow props. Select.Portal is optional.

Props

Select.Root

SelectItem is { label: string; value: string } — disabling is done per-Option.

Select.Value

Select.Option

Select.Trigger, Select.Positioner, and Select.Popup take no additional props beyond standard HTML attributes for their default element. Select.Portal accepts root.

Styling

Each part emits data-* attributes you can target with any CSS solution:

The positioner exposes anchor/viewport geometry as CSS variables (and sets an inline max-height to the available viewport height):