SelectItem

Renders a select item inside a SelectList or SelectPopover.

The role attribute will be automatically set on the item based on the list's own role attribute. For example, if the SelectPopover component's role attribute is set to listbox (which is the default), the item role will be set to option.

By default, the value prop will be rendered as the children, but this can be overriden if a custom children is provided.

Code examples

<SelectProvider>
  <Select />
  <SelectPopover>
    <SelectItem value="Apple" />
    <SelectItem value="Orange" />
  </SelectPopover>
</SelectProvider>
<SelectProvider>
  <Select />
  <SelectPopover>
    <SelectItem value="Apple" />
    <SelectItem value="Orange" />
  </SelectPopover>
</SelectProvider>

Optional Props

`accessibleWhenDisabled`

boolean | undefined
boolean | undefined

Indicates whether the element should be focusable even when it is disabled.

This is important when discoverability is a concern. For example:

A toolbar in an editor contains a set of special smart paste functions that are disabled when the clipboard is empty or when the function is not applicable to the current content of the clipboard. It could be helpful to keep the disabled buttons focusable if the ability to discover their functionality is primarily via their presence on the toolbar.

Learn more on Focusability of disabled controls⁠.

Live examples

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

`autoFocus`

boolean | undefined = false
boolean | undefined = false

Automatically focuses the element upon mounting, similar to the native autoFocus prop. This addresses an issue where the element with the native autoFocus attribute might receive focus before React effects are executed.

The autoFocus prop can also be used with Focusable elements within a Dialog component, establishing the initial focus as the dialog opens.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

Warning on Dialog hidePreventing users from accidentally closing a modal Dialog component with unsaved changes by displaying a nested confirmation dialog.

Dialog with React RouterUsing React Router to create a modal Dialog that's controlled by the browser history.

Nested DialogRendering a modal Dialog to confirm an action inside another modal dialog using React.

`blurOnHoverEnd`

BooleanOrCallback<React.MouseEvent<HTMLElement, MouseEvent>> | undefined
BooleanOrCallback<React.MouseEvent<HTMLElement, MouseEvent>> | undefined

Determines if the composite item should lose focus when the mouse leaves. By default, this is set to true if focusOnHover is true.

Live examples

Navigation MenubarUsing Menubar, Menu, and Portal to create an accessible, tabbable navigation menu widget with links and menu buttons that expand on hover and focus.

Combobox with integrated filterFiltering options in a Combobox component through an abstracted implementation using React.useDeferredValue, resulting in a simple higher-level API.

Submenu with ComboboxNesting Notion-style dropdown menus with search & autocomplete features by combining Menu with Combobox.

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

Command MenuCombining Dialog and Combobox to enable users to search a command list in a Raycast-style modal.

Select with Combobox and TabsAbstracting Select to work alongside Combobox and Tab components, presenting a searchable, tabbed dropdown.

`clickOnEnter`

boolean | undefined = true
boolean | undefined = true

If set to true, pressing the enter key while this element is focused will trigger a click on the element, regardless of whether it's a native button or not. If this prop is set to false, pressing enter will not initiate a click.

`clickOnSpace`

boolean | undefined = true
boolean | undefined = true

If set to true, pressing and releasing the space key while this element is focused will trigger a click on the element, regardless of whether it's a native button or not. If this prop is set to false, space will not initiate a click.

`disabled`

boolean | undefined = false
boolean | undefined = false

Determines if the element is disabled. This sets the aria-disabled attribute accordingly, enabling support for all elements, including those that don't support the native disabled attribute.

This feature can be combined with the accessibleWhenDisabled prop to make disabled elements still accessible via keyboard.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

SubmenuRendering nested Menu components to create a dropdown menu with submenus that open when hovering over the parent menu item.

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

Context menuShowing Menu when right-clicking on an element using the getAnchorRect prop to determine the position of the popover.

`focusable`

boolean | undefined = true
boolean | undefined = true

Determines if Focusable features should be active on non-native focusable elements.

Note: This prop only turns off the additional features provided by the Focusable component. Non-native focusable elements will lose their focusability entirely. However, native focusable elements will retain their inherent focusability, but without added features such as improved autoFocus, accessibleWhenDisabled, onFocusVisible, etc.

`focusOnHover`

BooleanOrCallback<React.MouseEvent<HTMLElement, MouseEvent>> | undefined = true
BooleanOrCallback<React.MouseEvent<HTMLElement, MouseEvent>> | undefined = true

Determines if the composite item should be focused when hovered over.

Note that the actual DOM focus will stay on the composite element. This item will get the data-active-item attribute so it can be styled as if it's focused.

Live examples

Multi-selectable ComboboxAllowing Combobox to select multiple options by passing an array value to the selectedValue prop.

Combobox with integrated filterFiltering options in a Combobox component through an abstracted implementation using React.useDeferredValue, resulting in a simple higher-level API.

Textarea with inline ComboboxRendering Combobox as a textarea element to create an accessible multiline textbox in React. Inserting specific characters triggers a popup with dynamic suggestions.

Navigation MenubarUsing Menubar, Menu, and Portal to create an accessible, tabbable navigation menu widget with links and menu buttons that expand on hover and focus.

Submenu with ComboboxNesting Notion-style dropdown menus with search & autocomplete features by combining Menu with Combobox.

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

`getItem`

((props: CollectionStoreItem) => CollectionStoreItem) | undefined
((props: CollectionStoreItem) => CollectionStoreItem) | undefined

A memoized function that returns props to be passed with the item during its registration in the store.

Code examples

const getItem = useCallback((data) => ({ ...data, custom: true }), []);
<CollectionItem getItem={getItem} />
const getItem = useCallback((data) => ({ ...data, custom: true }), []);
<CollectionItem getItem={getItem} />

`hideOnClick`

BooleanOrCallback<React.MouseEvent<HTMLElement, MouseEvent>> | undefined
BooleanOrCallback<React.MouseEvent<HTMLElement, MouseEvent>> | undefined

Whether to hide the select when this item is clicked. By default, it's true when the value prop is also provided.

`id`

string | undefined
string | undefined

The unique ID of the item. This will be used to register the item in the store and for the element's id attribute. If not provided, a unique ID will be automatically generated.

Live examples

Combobox with TabsOrganizing Combobox with Tab components that support mouse, keyboard, and screen reader interactions. The UI remains responsive by using React.startTransition.

Tab with React RouterUsing React Router to create Tab links and tab panels controlled by the browser history, while maintaining keyboard navigation.

Animated TabPanelUsing plain CSS transitions to slide in and out TabPanel components as they are expanded.

Select with Combobox and TabsAbstracting Select to work alongside Combobox and Tab components, presenting a searchable, tabbed dropdown.

`moveOnKeyPress`

BooleanOrCallback<React.KeyboardEvent<HTMLElement>> | undefined = true
BooleanOrCallback<React.KeyboardEvent<HTMLElement>> | undefined = true

Determines if pressing arrow keys while this item is in focus should move focus to a different item.

Note: To entirely disable focus moving within a composite widget, you can use the focusOnMove prop on the composite component instead. If you want to control the behavior only when arrow keys are pressed, where focusOnMove may not be applicable, this prop must be set on all composite items because they each manage their own key presses, as well as on the composite component itself.

Code examples

<Composite moveOnKeyPress={false}>
  <CompositeItem moveOnKeyPress={false} />
  <CompositeItem moveOnKeyPress={false} />
</Composite>
<Composite moveOnKeyPress={false}>
  <CompositeItem moveOnKeyPress={false} />
  <CompositeItem moveOnKeyPress={false} />
</Composite>

`onFocusVisible`

BivariantCallback<(event: React.SyntheticEvent<HTMLElement, Event>) => void> | undefined
BivariantCallback<(event: React.SyntheticEvent<HTMLElement, Event>) => void> | undefined

Custom event handler invoked when the element gains focus through keyboard interaction or a key press occurs while the element is in focus. This is the programmatic equivalent of the data-focus-visible attribute.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples

Navigation MenubarUsing Menubar, Menu, and Portal to create an accessible, tabbable navigation menu widget with links and menu buttons that expand on hover and focus.

Custom CheckboxRendering a visually hidden Checkbox using the VisuallyHidden component to show a custom checkbox presentation in React.

`render`

RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>> | undefined
RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>> | undefined

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Check out the Composition guide for more details.

`rowId`

string | undefined
string | undefined

The id that will be used to group items in the same row. This is usually retrieved by the CompositeRow component through context so in most cases you don't need to set it manually.

`setValueOnClick`

BooleanOrCallback<React.MouseEvent<HTMLElement, MouseEvent>> | undefined
BooleanOrCallback<React.MouseEvent<HTMLElement, MouseEvent>> | undefined

Whether to set the select value with this item's value, if any, when this item is clicked. By default, it's true when the value prop is also provided.

Live examples

Select with Next.js App RouterControlling the value of a Select component via the URL using the Next.js App Router and React.useOptimistic to ensure a responsive and accessible UI.

`shouldRegisterItem`

boolean | undefined
boolean | undefined

Determines if the item should be registered as part of the collection. If this is set to false, the item won't be accessible via arrow keys.

`store`

SelectStore<SelectStoreValue> | undefined
SelectStore<SelectStoreValue> | undefined

Object returned by the useSelectStore hook. If not provided, the parent SelectList or SelectPopover components' context will be used.

`tabbable`

boolean | undefined
boolean | undefined

When the tabbable prop is set to true, the roving tabindex⁠ method is partially disabled for this element. This means that the tabIndex prop won't be assigned -1 when the item is inactive. In addition to using arrow keys, users will be able to tab to this element, leading to the composite widget no longer existing as a single tab stop.

As per the ARIA spec⁠:

Authors SHOULD ensure that a composite widget exists as a single navigation stop within the larger navigation system of the web page.

Additionally, as stated in RFC-2119⁠:

SHOULD This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

Therefore, while this may be allowed, you should think carefully about the implications of using this prop.

Note: This prop has no effect when the virtualFocus option is enabled.

Live examples

Navigation MenubarUsing Menubar, Menu, and Portal to create an accessible, tabbable navigation menu widget with links and menu buttons that expand on hover and focus.

`value`

string | undefined
string | undefined

The value of the item. This will be rendered as the children by default.

If setValueOnClick is set to true, the value state will be set to this value when the user clicks on it.
If setValueOnMove is set to true, the value state will be set to this value when the user moves to it (which is usually the case when moving through the items using the keyboard).

Live examples

Form with SelectCombining Form and Select to create an accessible custom select widget that works with the browser's built-in validation and native form submission.

Animated SelectAnimating Select using CSS transitions in React. The component waits for the transition to finish before completely hiding the popover.

Select with ComboboxCombining Select and Combobox to create a dropdown with a search field that can be used to filter items.

Select GridUsing Select with SelectPopover rendered with the grid role to create a bidimensional list of selectable items.

SelectGroupSeparating Select items into groups using the SelectGroup and SelectGroupLabel components.

Select with custom itemsRendering Select with a custom styled value and SelectItem's children.

Code examples

<SelectItem value="Apple" />
<SelectItem value="Apple" />

`preventScrollOnKeyDown`

BooleanOrCallback<React.KeyboardEvent<HTMLElement>> | undefined = false
BooleanOrCallback<React.KeyboardEvent<HTMLElement>> | undefined = false

Deprecated: Use CSS scroll-margin⁠ instead.

Whether the scroll behavior should be prevented when pressing arrow keys on the first or the last items.

SelectItem

Live examples

Live examples

Live examples

Live examples

Live examples

Code examples

Live examples

Code examples

Live examples

Live examples

Live examples

Live examples

Code examples

Stay tuned