Ariakit
/

useMenuStore

Menu

Creates a menu store to control the state of Menu components.

Code examples

const menu = useMenuStore({ placement: "top" });



<MenuButton store={menu}>Edit</MenuButton>

<Menu store={menu}>

  <MenuItem>Undo</MenuItem>

  <MenuItem>Redo</MenuItem>

</Menu>

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 base 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 includesBaseElement prop will also default to true, which means the base 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.

combobox

ComboboxStore<ComboboxStoreSelectedValue> | null | undefined

A reference to a combobox store. It's automatically set when composing Menu with Combobox.

defaultActiveId

string | null | undefined

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.

defaultItems

T[] | undefined = []

The defaut value for the items state.

defaultOpen

boolean | undefined = false

Whether the content should be visible by default.

defaultValues

T | undefined = {}

The default values for the values state.

Live examples

MenuItemCheckboxRendering a dropdown Menu using the MenuItemCheckbox component with the values and setValues props from MenuProvider to control the checked items.
MenuItemRadioRendering Menu using MenuItemRadio as children and the values prop from MenuProvider to control the checked item.

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.

focusLoop

boolean | Orientation = false

Determines how the focus behaves when the user reaches the end of the composite widget.

On one-dimensional composite widgets:

  • true loops from the last item to the first item and vice-versa.

  • horizontal loops only if orientation is horizontal or not set.

  • vertical loops only if orientation is vertical or not set.

  • If includesBaseElement is set to true (or activeId is initially set to null), the composite element will be focused in between the last and first items.

On two-dimensional composite widgets (when using CompositeRow or explicitly passing a rowId prop to composite items):

  • true loops from the last row/column item to the first item in the same row/column and vice-versa. If it's the last item in the last row, it moves to the first item in the first row and vice-versa.

  • horizontal loops only from the last row item to the first item in the same row.

  • vertical loops only from the last column item to the first item in the column row.

  • If includesBaseElement is set to true (or activeId is initially set to null), vertical loop will have no effect as moving down from the last row or up from the first row will focus on the composite element.

  • If focusWrap matches the value of focusLoop, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.

Live examples

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

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.

focusWrap

boolean | Orientation = false

Works only on two-dimensional composite widgets.

If enabled, moving to the next item from the last one in a row or column will focus on the first item in the next row or column and vice-versa.

  • true wraps between rows and columns.

  • horizontal wraps only between rows.

  • vertical wraps only between columns.

  • If focusLoop matches the value of focusWrap, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.

hideTimeout

number | undefined = 0

The amount of time in milliseconds to wait before hiding the popup. It defaults to the value passed to timeout.

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.
Tooltip with Framer MotionAbstracting Tooltip into a reusable custom component that uses Framer Motion to create smooth initial and exit animations.

includesBaseElement

boolean = false

Indicates if the composite base element (the one with a composite role⁠) should be part of the focus order when navigating with arrow keys. In other words, moving to the previous element when the first item is in focus will focus on the composite element itself. The same applies to the last item when moving to the next element.

Live examples

Submenu with ComboboxNesting Notion-style dropdown menus with search & autocomplete features by combining Menu with Combobox.
Command MenuCombining Dialog and Combobox to enable users to search a command list in a Raycast-style modal.

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.

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 Framer MotionAbstracting Menu into a reusable dropdown menu component that uses Framer 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.

parent

MenuStore<MenuStoreValues> | null | undefined

A reference to a parent menu store. It's automatically set when nesting menus in the React tree. You should manually set this if menus aren't nested in the React tree.

Live examples

MenubarRender a visually persistent menu similar to those found near the top of the window in desktop apps. This component is based on the WAI-ARIA Menubar Pattern.
SubmenuRendering nested Menu components to create a dropdown menu with submenus that open when hovering over the parent menu item.
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.

placement

Placement = "bottom-start"

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 Select with SelectPopover 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.

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.

setActiveId

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

A callback that gets called when the activeId state changes.

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 });

setValues

BivariantCallback<(values: T) => void> | undefined

A callback that gets called when the values state changes.

Live examples

MenuItemCheckboxRendering a dropdown Menu using the MenuItemCheckbox component with the values and setValues props from MenuProvider to control the checked items.
Submenu with ComboboxNesting Notion-style dropdown menus with search & autocomplete features by combining Menu with Combobox.

showTimeout

number | undefined

The amount of time in milliseconds to wait before showing the popup. It defaults to the value passed to timeout.

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.
Submenu with ComboboxNesting Notion-style dropdown menus with search & autocomplete features by combining Menu with Combobox.

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.

timeout

number = 500

The amount of time in milliseconds to wait before showing and hiding the popup. To control the delay for showing and hiding separately, use showTimeout and hideTimeout.

values

T

A map of names and values that will be used by the MenuItemCheckbox and MenuItemRadio components.

Live examples

MenuItemCheckboxRendering a dropdown Menu using the MenuItemCheckbox component with the values and setValues props from MenuProvider to control the checked items.
Submenu with ComboboxNesting Notion-style dropdown menus with search & autocomplete features by combining Menu with Combobox.

virtualFocus

boolean = false

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

Select with Combobox and TabsAbstracting Select to work alongside Combobox and Tab components, presenting a searchable, tabbed 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.

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.

combobox

ComboboxStore<ComboboxStoreSelectedValue> | null | undefined

A reference to a combobox store. It's automatically set when composing Menu with Combobox.

parent

MenuStore<MenuStoreValues> | null | undefined

A reference to a parent menu store. It's automatically set when nesting menus in the React tree. You should manually set this if menus aren't nested in the React tree.

Live examples

MenubarRender a visually persistent menu similar to those found near the top of the window in desktop apps. This component is based on the WAI-ARIA Menubar Pattern.
SubmenuRendering nested Menu components to create a dropdown menu with submenus that open when hovering over the parent menu item.
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.

setValue

BivariantCallback<(name: string, value: SetStateAction<T[string]>) => void>

Sets a specific menu value.

Live examples

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

Code examples

store.setValue("watching", ["issues"]);

store.setValue("watching", (value) => [...value, "issues"]);

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());

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);

setBaseElement

SetState<HTMLElement | null>

Sets the baseElement state.

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 Select with SelectPopover 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

(skip?: number | undefined) => string | null | undefined

Returns the id of the next enabled item based on the current activeId state.

Code examples

const nextId = store.next();

const nextNextId = store.next(2);

previous

(skip?: number | undefined) => string | null | undefined

Returns the id of the previous enabled item based on the current activeId state.

Code examples

const previousId = store.previous();

const previousPreviousId = store.previous(2);

up

(skip?: number | undefined) => string | null | undefined

Returns the id of the enabled item above based on the current activeId state.

Code examples

const upId = store.up();

const upUpId = store.up(2);

down

(skip?: number | undefined) => string | null | undefined

Returns the id of the enabled item below based on the current activeId state.

Code examples

const downId = store.down();

const downDownId = store.down(2);

first

() => string | null | undefined

Returns the id of the first enabled item.

last

() => string | null | undefined

Returns the id of the last enabled item.

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();

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();

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");

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.

setPopoverElement

SetState<HTMLElement | null>

Sets the popover element.

setArrowElement

SetState<HTMLElement | null>

Sets the arrow element.

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.

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 Framer MotionUsing Framer 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.

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.

toggle

() => void

Toggles the open 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.

setContentElement

SetState<HTMLElement | null>

Sets the contentElement state.

setDisclosureElement

SetState<HTMLElement | null>

Sets the disclosureElement state.

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.

setValues

SetState<T>

Sets the values state.

Code examples

store.setValues({ watching: ["issues"] });

store.setValues((values) => ({ ...values, watching: ["issues"] }));

setAutoFocusOnShow

SetState<boolean>

Sets the autoFocusOnShow state.

Live examples

Sliding MenuRendering nested Menu components to create submenus that slide in and out using CSS Scroll Snap.

hideAll

() => void

Hides the menu and all its parent menus.

Live examples

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

setInitialFocus

SetState<"first" | "last" | "container">

Sets the initialFocus state.

getState

() => S

Returns the current store state.

setState

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

Sets a state value.

useState

UseState<StoreState<T>>

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⁠