Select

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

Anatomy

To set up the select correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the Select component in your project. Let's take a look at the most basic example:

Example not found

Example not found

Example not found

Example not found

Controlled Value

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

Example not found

Example not found

Example not found

Example not found

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.

Example not found

Example not found

Example not found

Example not found

Multiple Selection

To enable multiple item selection:

Example not found

Example not found

Example not found

Example not found

Form Library

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

Example not found

Example not found

Example not found

Example not found

Field Component

The Field component helps manage form-related state and accessibility attributes of a select. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility.

Example not found

Example not found

Example not found

Example not found

Async Loading

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

Example not found

Example not found

Example not found

Example not found

Root Provider

The RootProvider component provides a context for the select. It accepts the value of the useSelect hook. You can leverage it to access the component state and methods from outside the select.

Example not found

Example not found

Example not found

Example not found

If you're using the RootProvider component, you don't need to use the Root component.

Select on Highlight

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

Example not found

Example not found

Example not found

Example not found

Maximum Selected Items

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

Example not found

Example not found

Example not found

Example not found

Lazy Mount

The lazyMount and unmountOnExit props allow you to control when the select content is mounted and unmounted from the DOM. This can improve performance by only rendering the content when needed.

Example not found

Example not found

Example not found

Example not found

Guides

Type-Safety

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

This is particularly useful when building reusable select components with custom props and consistent styling.

import { Select as ArkSelect, type CollectionItem } from '@ark-ui/react/select'
import { createListCollection } from '@ark-ui/react/collection'

interface SelectProps<T extends CollectionItem> extends ArkSelect.RootProps<T> {}

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

Then, you can use the Select component as follows:

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

Usage in Popover or Dialog

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 height and width

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

Content

Control

HiddenSelect

Indicator

ItemGroupLabel

ItemGroup

ItemIndicator

Item

ItemText

Label

List

Positioner

RootProvider

Trigger

ValueText

Context

These are the properties available when using Select.Context, useSelectContext hook or useSelect hook.

API

Accessibility

Complies with the Listbox WAI-ARIA design pattern.

Keyboard Support