Ariakit
/

Select

Renders a custom select element that controls the visibility of either a SelectList or a SelectPopover component.

By default, the value state is rendered as the children, followed by a SelectArrow component. This can be customized by passing different children to the component.

Code examples

Optional Props


accessibleWhenDisabled

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


autoFocus

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.

Live examples


clickOnEnter

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

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

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.

Live examples


focusable

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.

Live examples


form

string | undefined

moveOnKeyDown

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

Determines whether pressing arrow keys will move the active item even when the SelectList or SelectPopover components are hidden.


name

string | undefined

onFocusVisible

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.

Live examples


render

RenderProp<React.HTMLAttributes<any> & React.RefAttributes<any>> | 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.


required

boolean | undefined

showOnKeyDown

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

Determines if the SelectList or SelectPopover components will appear when the user uses arrow keys while the select element is in focus.

Live examples


store

SelectStore<SelectStoreValue> | undefined

Object returned by the useSelectStore hook. If not provided, the closest SelectProvider component's context will be used.


toggleOnClick

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

Determines if toggle should be invoked on click. By default, the SelectList or SelectPopover components are displayed on press (on mouse/key down).

Note: When set to true, this prop supersedes the toggleOnPress prop.


toggleOnPress

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

Determines whether pressing Space, Enter, or a mouse down event will toggle the SelectList or SelectPopover components.

Note: This prop is disregarded if toggleOnClick is set to true.


typeahead

boolean | undefined = true

When enabled, pressing printable character keys will move focus to the next composite item that starts with the entered characters.

Follow updates

Join 1,000+ subscribers and receive monthly updates with the latest improvements on API Reference.

Read latest issue

No Spam. Unsubscribe at any time.