Menu
A list of options that appears when a user interacts with a button.
Anatomy
To set up the menu correctly, you’ll need to understand its anatomy and how we name its parts.
Each part includes a
data-partattribute to help identify them in the DOM.
Examples
Learn how to use the Menu component in your project. Let’s take a look at the
most basic example:
import { Menu } from '@ark-ui/react'
const Basic = () => (
<Menu.Root>
<Menu.ContextTrigger>
<div style={{ width: '100%', height: '20rem', border: '1px solid lightgray' }}>
Some content
</div>
</Menu.ContextTrigger>
<Menu.Positioner>
<Menu.Content>
<Menu.Item id="search">Search</Menu.Item>
<Menu.Item id="undo">Undo</Menu.Item>
<Menu.Item id="delivery" disabled>
Delivery
</Menu.Item>
<Menu.Item id="unlink">Unlink</Menu.Item>
</Menu.Content>
</Menu.Positioner>
</Menu.Root>
)
import { Menu } from '@ark-ui/react'
const Basic = () => (
<Menu.Root>
<Menu.Trigger>Open menu</Menu.Trigger>
<Menu.Positioner>
<Menu.Content>
<Menu.Item id="search">Search</Menu.Item>
<Menu.Item id="undo">Undo</Menu.Item>
<Menu.Item id="delivery" disabled>
Delivery
</Menu.Item>
<Menu.Item id="unlink">Unlink</Menu.Item>
</Menu.Content>
</Menu.Positioner>
</Menu.Root>
)
import { Menu, Portal } from '@ark-ui/react'
const Basic = () => (
<Menu.Root>
<Menu.Trigger>Open menu</Menu.Trigger>
<Menu.Positioner>
<Menu.Content>
<Menu.Item id="new-tab">New Tab...</Menu.Item>
<Menu.Item id="new-win">New Window...</Menu.Item>
<Menu.Separator />
<Menu.Root>
<Menu.TriggerItem>Share ></Menu.TriggerItem>
<Portal>
<Menu.Positioner>
<Menu.Content>
<Menu.Item id="twitter">Twitter</Menu.Item>
<Menu.Item id="message">Message</Menu.Item>
</Menu.Content>
</Menu.Positioner>
</Portal>
</Menu.Root>
</Menu.Content>
</Menu.Positioner>
</Menu.Root>
)
Listening to item selection
Pass the onSelect prop to the Menu component to perform some custom logic when
an item is selected. The callback is invoked with the id of the item.
Story not availableimport { Menu } from '@ark-ui/react'
import { useState } from 'react'
const Controlled = () => {
const [isOpen, setIsOpen] = useState(false)
return (
<>
<button onClick={() => setIsOpen(!isOpen)}>Trigger from the outside</button>
<Menu.Root open={isOpen} onSelect={(id) => console.log(id)}>
<Menu.Trigger>Open menu</Menu.Trigger>
<Menu.Positioner>
<Menu.Content>
<Menu.Item id="search">Search</Menu.Item>
<Menu.Item id="undo">Undo</Menu.Item>
<Menu.Item id="delivery" disabled>
Delivery
</Menu.Item>
<Menu.Item id="unlink">Unlink</Menu.Item>
</Menu.Content>
</Menu.Positioner>
</Menu.Root>
</>
)
}
Story not availableGrouping menu items
When the number of menu items gets much, it might be useful to group related
menu items. To achieve this, render the Menu.ItemGroup component around the
Menu.Item components. The Menu.ItemGroupLabel component can be used to add a
label to the group.
Story not availableimport { Menu } from '@ark-ui/react'
const Group = () => (
<Menu.Root>
<Menu.Trigger>Open menu</Menu.Trigger>
<Menu.Positioner>
<Menu.Content>
<Menu.ItemGroup id="group-1">
<Menu.ItemGroupLabel htmlFor="group-1">Group 1</Menu.ItemGroupLabel>
<Menu.Item id="share">Share...</Menu.Item>
<Menu.Item id="move">Move...</Menu.Item>
</Menu.ItemGroup>
<Menu.ItemGroup id="group-2">
<Menu.ItemGroupLabel htmlFor="group-2">Group 2</Menu.ItemGroupLabel>
<Menu.Item id="rename">Rename...</Menu.Item>
<Menu.Item id="delete">Delete...</Menu.Item>
</Menu.ItemGroup>
</Menu.Content>
</Menu.Positioner>
</Menu.Root>
)
Story not availableSeparating menu items
To separate menu items, render the Menu.Separator component.
Story not availableimport { Menu } from '@ark-ui/react'
const Separator = () => (
<Menu.Root>
<Menu.Trigger>Open menu</Menu.Trigger>
<Menu.Positioner>
<Menu.Content>
<Menu.Item id="search">Search</Menu.Item>
<Menu.Item id="undo">Undo</Menu.Item>
<Menu.Separator />
<Menu.Item id="delivery" disabled>
Delivery
</Menu.Item>
<Menu.Item id="unlink">Unlink</Menu.Item>
</Menu.Content>
</Menu.Positioner>
</Menu.Root>
)
Story not availableCheckbox and Radio option items
To show a checkbox or radio option item, use the Menu.OptionItem component.
Depending on the type prop, the item will be rendered as a checkbox or radio
option item. The name prop is used to group the items together, and the
value prop is used to identify the item.
To manage the state of the option items pass the value and onValueChange
props to the Menu component.
Story not availableimport { Menu } from '@ark-ui/react'
import { useState } from 'react'
const Options = () => {
const [value, setValue] = useState<Record<string, string | string[]>>({
framework: '',
libraries: [],
})
return (
<Menu.Root
value={value}
onValueChange={(data) => {
setValue((prev) => ({
...prev,
[data.name]: data.value,
}))
}}
>
<Menu.Trigger>Open menu</Menu.Trigger>
<Menu.Positioner>
<Menu.Content>
<Menu.ItemGroup id="radio-group">
<Menu.ItemGroupLabel htmlFor="radio-group">Radio Group</Menu.ItemGroupLabel>
<Menu.OptionItem name="framework" type="radio" value="react">
{({ isChecked }) => <>{isChecked ? '✅' : ''} React</>}
</Menu.OptionItem>
<Menu.OptionItem name="framework" type="radio" value="solid">
{({ isChecked }) => <>{isChecked ? '✅' : ''} Solid</>}
</Menu.OptionItem>
<Menu.OptionItem name="framework" type="radio" value="vue">
{({ isChecked }) => <>{isChecked ? '✅' : ''} Vue</>}
</Menu.OptionItem>
</Menu.ItemGroup>
<Menu.ItemGroup id="checkbox-group">
<Menu.ItemGroupLabel htmlFor="checkbox-group">Checkbox Group</Menu.ItemGroupLabel>
<Menu.OptionItem name="libraries" type="checkbox" value="zag-js">
{({ isChecked }) => <>{isChecked ? '✅' : ''} zag-js</>}
</Menu.OptionItem>
<Menu.OptionItem name="libraries" type="checkbox" value="ark">
{({ isChecked }) => <>{isChecked ? '✅' : ''} ark</>}
</Menu.OptionItem>
<Menu.OptionItem name="libraries" type="checkbox" value="panda">
{({ isChecked }) => <>{isChecked ? '✅' : ''} panda</>}
</Menu.OptionItem>
<Menu.OptionItem name="libraries" type="checkbox" value="chakra">
{({ isChecked }) => <>{isChecked ? '✅' : ''} chakra</>}
</Menu.OptionItem>
</Menu.ItemGroup>
</Menu.Content>
</Menu.Positioner>
</Menu.Root>
)
}
Story not availableAPI Reference
Item
| Prop | Type | Default |
|---|---|---|
idThe `id` of the menu item option. | string | |
asChildRender as a different element type. | boolean | |
closeOnSelectWhether the menu should be closed when the option is selected. | boolean | |
disabledWhether the menu item is disabled | boolean | |
valueTextThe textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | string |
Root
| Prop | Type | Default |
|---|---|---|
anchorPointThe positioning point for the menu. Can be set by the context menu trigger or the button trigger. | Point | |
aria-labelThe accessibility label for the menu | string | |
closeOnSelectWhether to close the menu when an option is selected | boolean | |
dirThe document's text/writing direction. | 'ltr' | 'rtl' | "ltr" |
getRootNodeA root node to correctly resolve document in custom environments. E.x.: Iframes, Electron. | () => Node | ShadowRoot | Document | |
highlightedIdThe `id` of the active menu item. | string | |
idThe unique identifier of the machine. | string | |
idsThe ids of the elements in the menu. Useful for composition. | Partial<{
trigger: string
contextTrigger: string
content: string
label(id: string): string
group(id: string): string
positioner: string
arrow: string
}> | |
lazyMountWhether to enable lazy mounting | boolean | false |
loopWhether to loop the keyboard navigation. | boolean | |
onExitCompleteFunction called when the animation ends in the closed state. | () => void | |
onFocusOutsideFunction called when the focus is moved outside the component | (event: FocusOutsideEvent) => void | |
onInteractOutsideFunction called when an interaction happens outside the component | (event: InteractOutsideEvent) => void | |
onOpenChangeFunction called when the menu opens or closes | (details: OpenChangeDetails) => void | |
onPointerDownOutsideFunction called when the pointer is pressed down outside the component | (event: PointerDownOutsideEvent) => void | |
onSelectFunction called when a menu item is selected. | (details: SelectionDetails) => void | |
onValueChangeCallback to be called when the menu values change (for radios and checkboxes). | (details: ValueChangeDetails) => void | |
openWhether the menu is open | boolean | |
positioningThe options used to dynamically position the menu | PositioningOptions | |
presentWhether the node is present (controlled by the user) | boolean | |
unmountOnExitWhether to unmount on exit. | boolean | false |
valueThe values of radios and checkboxes in the menu. | Record<string, string | string[]> |
Arrow
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Content
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Trigger
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
ArrowTip
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
ItemGroup
| Prop | Type | Default |
|---|---|---|
idThe `id` of the element that provides accessibility label to the option group | string | |
asChildRender as a different element type. | boolean |
Separator
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
OptionItem
| Prop | Type | Default |
|---|---|---|
nameThe option's name as specified in menu's `context.values` object | string | |
typeWhether the option is a radio or a checkbox | 'checkbox' | 'radio' | |
valueThe value of the option | string | |
asChildRender as a different element type. | boolean | |
closeOnSelectWhether the menu should be closed when the option is selected. | boolean | |
disabledWhether the menu item is disabled | boolean | |
onCheckedChangeFunction called when the option state is changed | (checked: boolean) => void | |
valueTextThe textual value of the option. Used in typeahead navigation of the menu. If not provided, the text content of the menu item will be used. | string |
Positioner
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
TriggerItem
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
ContextTrigger
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
ItemGroupLabel
| Prop | Type | Default |
|---|---|---|
htmlFor | string | |
asChildRender as a different element type. | boolean |
Previous
ComboboxNext
Date Picker