Ariakit
/

useComboboxStore

Combobox

Creates a combobox store to control the state of Combobox components.

Code examples

const combobox = useComboboxStore();



<ComboboxProvider store={combobox}>

  <Combobox />

  <ComboboxPopover>

    <ComboboxItem value="Apple" />

    <ComboboxItem value="Banana" />

    <ComboboxItem value="Orange" />

  </ComboboxPopover>

</ComboboxProvider>

Optional Props

activeId

string | null | undefined

The current active item id. The active item is the element within the composite widget that has either DOM or virtual focus (in case virtualFocus is enabled).

  • null represents the composite element (the one with a composite role⁠). Users will be able to navigate out of it using arrow keys.

  • If activeId is initially set to null, the compositeElementInFocusOrder prop will also default to true, which means the composite element itself will have focus and users will be able to navigate to it using arrow keys.

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.

compositeElementInFocusOrder

boolean

Defaults to true, or false when a ComboboxSelect is rendered.

defaultActiveId

string | null | undefined = null

The composite item id that should be active by default when the composite widget is rendered. If null, the composite element itself will have focus and users will be able to navigate to it using arrow keys. If undefined, the first enabled item will be focused.

defaultInputValue

string | undefined = ""

The initial value of the combobox input.

defaultItems

T[] | undefined = []

The default value for the items state.

defaultOpen

boolean | undefined = false

Whether the content should be visible by default.

defaultSelectedValue

MutableValue<T> | undefined

The initial value of the selectedValue state. This can be a string or an array of strings. If it's an array, the combobox is considered multi-selectable.

The default value is "" for a plain combobox. When a ComboboxSelect is rendered, the first enabled item with a defined value is selected instead. Pass "" explicitly to prevent this automatic selection.

Live examples

Form with SelectCombining Form and Combobox to create an accessible custom select widget that works with the browser's built-in validation and native form submission.
Animated SelectAnimating a Combobox select using CSS transitions in React. The component waits for the transition to finish before completely hiding the popover.
Searchable Combobox SelectCombining ComboboxSelect and ComboboxInput in the same Combobox provider to create a dropdown with a search field that filters its items.
Select groupSeparating Combobox items into groups using the ComboboxGroup and ComboboxGroupLabel components.
Combobox Select with Next.js App RouterControlling the selected value of a Combobox via the URL using the Next.js App Router and React.useOptimistic to ensure a responsive and accessible UI.
Combobox Select with TabsAbstracting Combobox and Tab components into a searchable, tabbed select dropdown.

disclosure

DisclosureStore | null | undefined

A reference to another disclosure store that controls another disclosure component to keep them in sync. Element states like contentElement and disclosureElement won't be synced. For that, use the store prop instead.

Live examples

Command MenuCombining Dialog and Combobox to enable users to search a command list in a Raycast-style modal.
Command Menu with TabsCombining Dialog, Tab, and Combobox from Ariakit React to build a command palette component.

focusLoop

boolean | Orientation

Defaults to true, or false when a ComboboxSelect is rendered.

focusShift

boolean = false

Works only on two-dimensional composite widgets.

If enabled, moving up or down when there's no next item or when the next item is disabled will shift to the item right before it.

Live examples

Command Menu with TabsCombining Dialog, Tab, and Combobox from Ariakit React to build a command palette component.

focusWrap

boolean | Orientation

Defaults to true, or false when a ComboboxSelect is rendered.

id

string

The ID of the composite store is used to reference elements within the composite widget before hydration. If not provided, a random ID will be generated.

inputValue

string

The combobox input value.

Live examples

Combobox with integrated filterFiltering options in a Combobox component through an abstracted implementation using React.useDeferredValue, resulting in a simple higher-level API.
Combobox with linksUsing a Combobox with items rendered as links that can be clicked with keyboard and mouse. This is useful for creating an accessible page search input in React.
Combobox filteringListing suggestions in a Combobox component based on the input value using React.startTransition to ensure the UI remains responsive during typing.
Multi-selectable ComboboxAllowing Combobox to select multiple options by passing an array value to the selectedValue prop.
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.
Command Menu with TabsCombining Dialog, Tab, and Combobox from Ariakit React to build a command palette component.

items

T[]

Lists all items along with their metadata. This state is automatically updated when an item is registered or unregistered using the registerItem function.

Live examples

Command Menu with TabsCombining Dialog, Tab, and Combobox from Ariakit React to build a command palette component.

open

boolean = false

Whether the content is visible.

Live examples

Combobox with linksUsing a Combobox with items rendered as links that can be clicked with keyboard and mouse. This is useful for creating an accessible page search input in React.
Dialog with React RouterUsing React Router to create a modal Dialog that's controlled by the browser history.
Menu with MotionAbstracting Menu into a reusable dropdown menu component that uses Motion to create smooth initial and exit animations.
Lazy PopoverLazy loading Popover using React.lazy and React.useTransition to avoid downloading additional code until the user interacts with the button.

orientation

Orientation = "vertical"

Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the orientation value determines which arrow keys can be used to move focus:

  • both: all arrow keys work.

  • horizontal: only left and right arrow keys work.

  • vertical: only up and down arrow keys work.

It doesn't have any effect on two-dimensional composites.

placement

Placement = "bottom"

The placement of the popover.

Live examples

Submenu with ComboboxNesting Notion-style dropdown menus with search & autocomplete features by combining Menu with Combobox.
Sliding MenuRendering nested Menu components to create submenus that slide in and out using CSS Scroll Snap.
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.
Selection PopoverShowing an inline Popover when a text is selected. This example uses the getAnchorRect prop to position the flyout relative to the selected text.
Standalone PopoverAbstracting the Popover component so that it can be used without PopoverDisclosure or PopoverAnchor. This example uses the getAnchorRect prop to determine the position of the popup.
Select gridUsing Combobox with ComboboxPopover rendered with the grid role to create a bidimensional list of selectable items.

popover

PopoverStore | null | undefined

A reference to another popover store that's controlling another popover to keep them in sync.

resetValueOnHide

boolean

Whether to reset the value when the combobox popover closes. This prop is automatically set to true by default if the combobox supports multiple selections. In other words, if the selectedValue or defaultSelectedValue props are arrays. However, when the combobox is connected to a tag store, the default is false so the input value is kept when the popover closes.

Live examples

Multi-selectable ComboboxAllowing Combobox to select multiple options by passing an array value to the selectedValue prop.
Menu with ComboboxCombining Menu and Combobox to create a dropdown menu with a search field that can be used to filter menu items.
Searchable Combobox SelectCombining ComboboxSelect and ComboboxInput in the same Combobox provider to create a dropdown with a search field that filters its items.
Submenu with ComboboxNesting Notion-style dropdown menus with search & autocomplete features by combining Menu with Combobox.
Command Menu with TabsCombining Dialog, Tab, and Combobox from Ariakit React to build a command palette component.
Combobox Select with TabsAbstracting Combobox and Tab components into a searchable, tabbed select dropdown.

rtl

boolean = false

Determines how the next and previous functions will behave. If rtl is set to true, they will be inverted.

This only affects the composite widget behavior. You still need to set dir="rtl" on HTML/CSS.

selectedValue

MutableValue<T>

The value(s) of the currently selected item(s). This can be a string or an array of strings. If it's an array, the combobox is considered multi-selectable.

Live examples

Multi-selectable ComboboxAllowing Combobox to select multiple options by passing an array value to the selectedValue prop.
Form with SelectCombining Form and Combobox to create an accessible custom select widget that works with the browser's built-in validation and native form submission.
Select gridUsing Combobox with ComboboxPopover rendered with the grid role to create a bidimensional list of selectable items.
Select with custom itemsRendering a Combobox select with a custom styled value and ComboboxItem's children.
Multi-selectable Combobox SelectAllowing the Combobox component to select multiple values by passing an array to the selectedValue prop on the ComboboxProvider component.
Toolbar with SelectRendering ComboboxSelect as a ToolbarItem inside a Toolbar.
Combobox Select with Next.js App RouterControlling the selected value of a Combobox via the URL using the Next.js App Router and React.useOptimistic to ensure a responsive and accessible UI.

selectOnMove

boolean = false

Whether the combobox selectedValue should be set when the active item changes by moving while ComboboxSelect is open. The selected value is always updated when moving while the select is closed.

Live examples

Select gridUsing Combobox with ComboboxPopover rendered with the grid role to create a bidimensional list of selectable items.
Select with custom itemsRendering a Combobox select with a custom styled value and ComboboxItem's children.

setActiveId

((activeId: string | null | undefined) => void) | undefined

A callback that gets called when the activeId state changes.

setInputValue

((value: string) => void) | undefined

A callback that gets called when the inputValue state changes.

Live examples

Combobox with integrated filterFiltering options in a Combobox component through an abstracted implementation using React.useDeferredValue, resulting in a simple higher-level API.
ComboboxGroupOrganizing Combobox items into labelled groups using the ComboboxGroup and ComboboxGroupLabel components in React.
Combobox with linksUsing a Combobox with items rendered as links that can be clicked with keyboard and mouse. This is useful for creating an accessible page search input in React.
Multi-selectable ComboboxAllowing Combobox to select multiple options by passing an array value to the selectedValue prop.
Menu with ComboboxCombining Menu and Combobox to create a dropdown menu with a search field that can be used to filter menu items.
Searchable Combobox SelectCombining ComboboxSelect and ComboboxInput in the same Combobox provider to create a dropdown with a search field that filters its items.

setItems

BivariantCallback<(items: T[]) => void> | undefined

A callback that gets called when the items state changes.

Code examples

const [items, setItems] = useState([]);

const collection = useCollectionStore({ items, setItems });

setMounted

((mounted: boolean) => void) | undefined

A callback that gets called when the mounted state changes.

Code examples

const [mounted, setMounted] = useState(false);

const disclosure = useDisclosureStore({ setMounted });

setOpen

((open: boolean) => void) | undefined

A callback that gets called when the open state changes.

Code examples

const [open, setOpen] = useState(false);

const disclosure = useDisclosureStore({ open, setOpen });

setSelectedValue

BivariantCallback<(value: MutableValue<T>) => void> | undefined

A callback that's invoked when the selectedValue state changes, typically when the user selects an item. This can be used to implement behavior like onSelect or onItemSelect.

Live examples

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

store

Store<Partial<S>> | undefined

Another store object that will be kept in sync with the original store.

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.

tag

TagStore | null | undefined

A reference to a tag store. It's automatically set when rendering a combobox within a tag list.

virtualFocus

boolean = true

If enabled, the composite element will act as an aria-activedescendant⁠ container instead of roving tabindex⁠. DOM focus will remain on the composite element while its items receive virtual focus.

In both scenarios, the item in focus will carry the data-active-item attribute.

Live examples

Combobox Select with TabsAbstracting Combobox and Tab components into a searchable, tabbed select dropdown.

animated

number | boolean | undefined

Deprecated: Manually setting the animated prop is no longer necessary. This will be removed in a future release.

Determines whether the content should animate when it is shown or hidden.

  • If true, the animating state will be true when the content is shown or hidden and it will wait for a CSS animation/transition to end before becoming false.

  • If it's set to a number, the animating state will be true when the content is shown or hidden and it will wait for the number of milliseconds to pass before becoming false.

defaultValue

string | undefined = ""

Deprecated: Use defaultInputValue instead.

The initial value of the combobox input.

includesBaseElement

boolean

Deprecated: Use compositeElementInFocusOrder instead.

Whether the composite element is in the arrow-key focus order.

resetValueOnSelect

boolean

Deprecated: Use the resetValueOnSelect prop on ComboboxItem instead.

Whether to reset the value when an item is selected. This prop is automatically set to true by default if the combobox supports multiple selections. In other words, if the selectedValue or defaultSelectedValue props are arrays.

setValue

((value: string) => void) | undefined

Deprecated: Use setInputValue instead.

A callback that gets called when the inputValue state changes.

value

string

Deprecated: Use inputValue instead.

The combobox input value.

Return Props

disclosure

DisclosureStore | null | undefined

A reference to another disclosure store that controls another disclosure component to keep them in sync. Element states like contentElement and disclosureElement won't be synced. For that, use the store prop instead.

Live examples

Command MenuCombining Dialog and Combobox to enable users to search a command list in a Raycast-style modal.
Command Menu with TabsCombining Dialog, Tab, and Combobox from Ariakit React to build a command palette component.

down

{ (options?: NextOptions | undefined): string | null | undefined; (skip?: number | undefined): string | null | undefined; }

Returns the id of the enabled item below based on the current activeId state. You can pass additional options to override the current state.

Code examples

const downId = store.down();

first

() => string | null | undefined

Returns the id of the first enabled item.

getState

() => S

Returns the current store state.

hide

() => void

Sets the open state to false.

Live examples

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.
Sliding MenuRendering nested Menu components to create submenus that slide in and out using CSS Scroll Snap.

item

(id: string | null | undefined) => T | null

Gets an item by its id.

Live examples

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

Code examples

const item = store.item("item-1");

last

() => string | null | undefined

Returns the id of the last enabled item.

move

(id?: string | null | undefined) => void

Moves focus to a given item id and sets it as the active item.

  • Passing null will focus on the composite element itself (the one with a composite role⁠). Users will be able to navigate out of it using arrow keys.

  • If you want to set the active item id without moving focus, use the setActiveId function instead.

Live examples

Select gridUsing Combobox with ComboboxPopover rendered with the grid role to create a bidimensional list of selectable items.

Code examples

// Moves focus to the composite element

store.move(null);

// Moves focus to the item with id "item-1"

store.move("item-1");

// Moves focus to the next item

store.move(store.next());

next

{ (options?: NextOptions | undefined): string | null | undefined; (skip?: number | undefined): string | null | undefined; }

Returns the id of the next enabled item based on the current activeId state. You can pass additional options to override the current state.

Code examples

const nextId = store.next();

previous

{ (options?: NextOptions | undefined): string | null | undefined; (skip?: number | undefined): string | null | undefined; }

Returns the id of the previous enabled item based on the current activeId state. You can pass additional options to override the current state.

Code examples

const previousId = store.previous();

registerItem

BivariantCallback<(item: T) => () => void>

Registers an item in the collection. This function returns a cleanup function that unregisters the item.

Code examples

const unregisterItem = store.registerItem({ id: "item-1" });

// on cleanup

unregisterItem();

render

() => void

A function that can be used to recompute the popover position. This is useful when the popover anchor changes in a way that affects the popover position.

Live examples

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.
Selection PopoverShowing an inline Popover when a text is selected. This example uses the getAnchorRect prop to position the flyout relative to the selected text.

renderItem

BivariantCallback<(item: T) => () => void>

Renders an item in the collection. This function returns a cleanup function that unmounts the item.

Code examples

const unrenderItem = store.renderItem({ id: "item-1" });

// on cleanup

unrenderItem();

resetInputValue

() => void

Resets the inputValue state to its initial value.

setActiveId

SetState<string | null | undefined>

Sets the activeId state without moving focus. If you want to move focus, use the move function instead.

Code examples

// Sets the composite element as the active item

store.setActiveId(null);

// Sets the item with id "item-1" as the active item

store.setActiveId("item-1");

// Sets the next item as the active item

store.setActiveId(store.next());

setAnchorElement

SetState<HTMLElement | null>

Sets the anchor element.

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.

setArrowElement

SetState<HTMLElement | null>

Sets the arrow element.

setCompositeElement

SetState<HTMLElement | null>

Sets the compositeElement state.

setContentElement

SetState<HTMLElement | null>

Sets the contentElement state.

setDisclosureElement

SetState<HTMLElement | null>

Sets the disclosureElement state.

When showing the content programmatically, set this to the element that should act as its trigger.

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.

Code examples

store.setDisclosureElement(triggerRef.current);

store.show();

setInputElement

SetState<HTMLElement | null>

Sets the inputElement state.

setInputValue

SetState<string>

Sets the inputValue state.

Live examples

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.

Code examples

store.setInputValue("Hello world");

store.setInputValue((value) => value + "!");

setLabelElement

SetState<HTMLElement | null>

Sets the labelElement state.

setOpen

SetState<boolean>

Sets the open state.

Live examples

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.

Code examples

store.setOpen(true);

store.setOpen((open) => !open);

setPopoverElement

SetState<HTMLElement | null>

Sets the popover element.

setSelectedValue

SetState<MutableValue<T>>

Sets the selectedValue state.

setSelectElement

SetState<HTMLElement | null>

Sets the selectElement state.

setSelectLabelElement

SetState<HTMLElement | null>

Sets the selectLabelElement state.

setState

<K extends keyof S>(key: K, value: SetStateAction<S[K]>) => void

Sets a state value.

show

() => void

Sets the open state to true.

Live examples

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.
Dialog with MotionUsing Motion to add initial and exit animations to a modal Dialog and its backdrop element.
Context menuShowing Menu when right-clicking on an element using the getAnchorRect prop to determine the position of the popover.
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.

tag

TagStore | null | undefined

A reference to a tag store. It's automatically set when rendering a combobox within a tag list.

toggle

() => void

Toggles the open state.

up

{ (options?: NextOptions | undefined): string | null | undefined; (skip?: number | undefined): string | null | undefined; }

Returns the id of the enabled item above based on the current activeId state. You can pass additional options to override the current state.

Code examples

const upId = store.up();

resetValue

() => void

Deprecated: Use resetInputValue instead.

Resets the inputValue state to its initial value.

setBaseElement

SetState<HTMLElement | null>

Deprecated: Use setCompositeElement instead.

Sets the composite element state.

setValue

SetState<string>

Deprecated: Use setInputValue instead.

Sets the inputValue state.

stopAnimation

() => void

Deprecated: Use setState("animating", false) instead.

Sets the animating state to false, which will automatically set the mounted state to false if it was true. This means that the content element can be safely unmounted.

useState

UseState<StoreState<T>>

Deprecated: Use useStoreState instead.

Re-renders the component when the state changes and returns the current state.

Stay tuned

Join 1,000+ subscribers and receive monthly tips & updates on new Ariakit content.

No spam. Unsubscribe anytime. Read latest issue⁠