Select

Displays a list of options for the user to pick from.

You can explore the select component in the following curated examples.

Anatomy

<Select.Root>
  <Select.Label />
  <Select.Control>
    <Select.Trigger>
      <Select.ValueText />
    </Select.Trigger>
    <Select.ClearTrigger />
    <Select.Indicator />
  </Select.Control>
  <Select.Positioner>
    <Select.Content>
      <Select.ItemGroup>
        <Select.ItemGroupLabel />
        <Select.Item>
          <Select.ItemText />
          <Select.ItemIndicator />
        </Select.Item>
      </Select.ItemGroup>
    </Select.Content>
  </Select.Positioner>
  <Select.HiddenSelect />
</Select.Root>

Examples

Controlled

Use the value and onValueChange props to control the selected items.

Root Provider

An alternative way to control the select is to use the RootProvider component and the useSelect hook. This way you can access the state and methods from outside the component.

Multiple

To enable multiple item selection:

Grouping

Grouping related options can be useful for organizing options into categories.

• Use the groupBy prop to configure the grouping of the items.
• Use the collection.group() method to get the grouped items.
• Use the Select.ItemGroup and Select.ItemGroupLabel components to render the grouped items.

Field

Use Field to manage form state, ARIA labels, helper text, and error text.

Form Usage

Here's an example of integrating the Select component with a form library.

Async Loading

Here's an example of how to load the items asynchronously when the select is opened.

Lazy Mount

Use lazyMount and unmountOnExit to control when content is mounted, improving performance.

Select on Highlight

Here's an example of automatically selecting items when they are highlighted (hovered or navigated to with keyboard).

Max Selection

Here's an example of limiting the number of items that can be selected in a multiple select.

Select All

Use selectAll() from the select context to select all items at once.

Overflow

For selects with many items, use positioning.fitViewport to ensure the dropdown fits within the viewport. Combine with a max-height on the content to enable scrolling.

Guides

Type Safety

The Select.RootComponent type enables you to create typed wrapper components that maintain full type safety for collection items.

const Select: ArkSelect.RootComponent = (props) => {
  return <ArkSelect.Root {...props}>{/* ... */}</ArkSelect.Root>
}

Use the wrapper with full type inference on onValueChange and other callbacks:

const App = () => {
  const collection = createListCollection({
    initialItems: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
    ],
  })
  return (
    <Select
      collection={collection}
      onValueChange={(e) => {
        // e.items is typed as Array<{ label: string, value: string }>
        console.log(e.items)
      }}
    >
      {/* ... */}
    </Select>
  )
}

Nested Usage

When using the Select component within a Popover or Dialog, avoid rendering its content within a Portal or Teleport.

This ensures the Select's content stays within the Popover/Dialog's DOM hierarchy rather than being portalled to the document body, maintaining proper interaction and accessibility behavior.

Hidden Select

The Select.HiddenSelect component renders a native HTML <select> element that's visually hidden but remains in the DOM. This component is essential for:

• Form submission: Native form submission and serialization work seamlessly since the actual <select> element exists in the DOM
• Browser auto-fill: Browsers can properly auto-fill the select based on previously submitted form data
• Progressive enhancement: Forms remain functional even if JavaScript fails to load

<Select.Root>
  <Select.HiddenSelect />
  {/* Other Select components */}
</Select.Root>

The hidden select automatically syncs with the Select component's value, ensuring form data is always up-to-date.

Empty State

You can create an empty state component that displays when there are no items in the collection. Use the useSelectContext hook to check the collection size:

const SelectEmpty = (props: React.ComponentProps<'div'>) => {
  const select = useSelectContext()
  if (select.collection.size === 0) {
    return <div {...props} role="presentation" />
  }
  return null
}

Then use it within your Select content:

<Select.Content>
  <SelectEmpty>No items to display</SelectEmpty>
  {/* Your items */}
</Select.Content>

Available Size

The following css variables are exposed to the Select.Positioner which you can use to style the Select.Content

/* width of the select trigger */
--reference-width: <pixel-value>;
/* width of the available viewport */
--available-width: <pixel-value>;
/* height of the available viewport */
--available-height: <pixel-value>;

For example, if you want to make sure the maximum height doesn't exceed the available height, you can use the following:

[data-scope='select'][data-part='content'] {
  max-height: calc(var(--available-height) - 100px);
}

API Reference

Props

Root

ClearTrigger

Renders a <button> element.

Content

Renders a <div> element.

Control

Renders a <div> element.

HiddenSelect

Renders a <select> element.

Indicator

Renders a <div> element.

ItemGroupLabel

Renders a <div> element.

ItemGroup

Renders a <div> element.

ItemIndicator

Renders a <div> element.

Item

Renders a <div> element.

ItemText

Renders a <div> element.

Label

Renders a <label> element.

List

Renders a <div> element.

Positioner

Renders a <div> element.

RootProvider

Trigger

Renders a <button> element.

ValueText

Renders a <span> element.

Context

API

Accessibility

Complies with the Listbox WAI-ARIA design pattern.

Keyboard Support