Menus
Material anchored menus, expressive selection/groups, read-only exposed menus, and editable/read-only exposed comboboxes with browser-native semantics.
Menus present a temporary list of actions or choices anchored to a trigger. Material defines the visual menu surface and item anatomy; React Aria supplies the browser menu interaction model.
import { Button, Menu, MenuItem, MenuSection } from '@m3-ui/ui';
<Menu
aria-label="Document actions"
trigger={<Button>Actions</Button>}
onAction={(key) => runAction(key)}
>
<MenuSection label="Edit">
<MenuItem id="rename">Rename</MenuItem>
<MenuItem id="duplicate" supportingText="Create a copy">
Duplicate
</MenuItem>
</MenuSection>
</Menu>When to use
Use a menu for a temporary list of actions or choices that should not occupy persistent screen space. Prefer visible buttons when actions are few and important enough to remain exposed. Use selection controls when choices should remain visible as form state.
Anchored menu behavior
placement, offset, and crossOffset configure browser overlay positioning without redefining Material menu geometry. React Aria owns roving focus, Arrow/Home/End navigation, typeahead, Escape/outside dismissal, and focus restoration.
MenuItem keeps leading/supporting/trailing slots visual while the item itself remains the semantic action. Sections use real section/header relationships; visual section variants do not invent a new selection model.
Selection and expressive groups
Set selectionMode="single" for one-of-many choices. React Aria exposes those items as menuitemradio; selectedLeading can swap the leading visual without changing the semantic label.
<Menu
aria-label="Text alignment"
selectionMode="single"
selectedKeys={selected}
onSelectionChange={setSelected}
trigger={<Button>Alignment</Button>}
>
<MenuSection variant="segmented">
<MenuItem id="left" leading="○" selectedLeading="✓">Left</MenuItem>
<MenuItem id="center" leading="○" selectedLeading="✓">Center</MenuItem>
<MenuItem id="right" leading="○" selectedLeading="✓">Right</MenuItem>
</MenuSection>
</Menu>Use selectionMode="multiple" for checkable choices; React Aria exposes them as menuitemcheckbox. MenuSection variant="segmented" tone="vibrant" applies the reviewed expressive group geometry and vibrant Material roles from generated canonical tokens.
For checkable menus that should remain open while several options are toggled, pass React Aria's shouldCloseOnSelect={false} through Menu.
Cascading submenus
MenuSubmenu composes a Material submenu on React Aria SubmenuTrigger. Arrow-key direction, hover disclosure, Escape, focus travel, logical RTL behavior, collision handling, and nested overlay placement stay React Aria-owned.
<Menu aria-label="Editor actions" trigger={<Button>Editor</Button>}>
<MenuItem id="undo">Undo</MenuItem>
<MenuSubmenu
aria-label="Format options"
trigger={<MenuItem id="format" trailing="›">Format</MenuItem>}
>
<MenuItem id="bold">Bold</MenuItem>
<MenuItem id="italic">Italic</MenuItem>
</MenuSubmenu>
</Menu>Do not attach a competing Arrow/Escape handler to submenu triggers; the wrapper intentionally delegates that interaction model to React Aria.
Exposed menu
ExposedMenu uses the Material text-field visual anchor for read-only menu selection.
<ExposedMenu
label="Density"
value={densityLabel}
onAction={(key) => selectDensity(key)}
>
<MenuItem id="compact">Compact</MenuItem>
<MenuItem id="standard">Standard</MenuItem>
</ExposedMenu>The anchor is a React Aria menu button rendered with the Material filled TextField presentation. React Aria MenuTrigger owns press normalization, ArrowDown/Enter/Space opening, popup/expanded ARIA, first-item focus, Escape/outside dismissal, and trigger focus restoration. It is intentionally not an editable textbox, combobox, or autocomplete. Do not attach competing pointer/keyboard/focus handlers or describe users as typing into it or filtering options unless a separate editable public API is composed.
Exposed dropdown menu
ExposedDropdownMenu is a separate public surface for combobox/listbox selection. It supports both editable and read-only input behavior while keeping the popup options in a listbox rather than pretending an editable text input is a menu trigger.
<ExposedDropdownMenu
aria-label="Density"
label="Density"
items={densityOptions}
value={density}
onSelectionChange={(value) => setDensity(value)}
isOpen={isOpen}
onOpenChange={setIsOpen}
inputValue={query}
onInputChange={setQuery}
/>When inputValue/onInputChange are supplied, users can edit the combobox text and the application owns filtering, remote search, or any other query policy. The component does not silently filter items; this keeps text editing and data policy explicit.
For a non-editable combobox/listbox presentation, set isReadOnly (or omit the editable input contract). This read-only mode is still ExposedDropdownMenu combobox/listbox semantics and is distinct from ExposedMenu, whose anchor remains a read-only menu disclosure.
Accessibility
Give menu triggers and menus meaningful names. Keep item labels usable for typeahead and accessible naming. Let the menu interaction model own arrow-key navigation and focus restoration rather than attaching competing keyboard handlers.
For ExposedMenu, preserve its read-only menu-button relationship; a text-field appearance does not make it a text input. For ExposedDropdownMenu, preserve the combobox/listbox relationship, keep editing focus on the input, and leave filtering policy to application code.
API reference
Menu
Material renderer around React Aria menu semantics and overlay positioning. RAC owns roving focus, Home/End/arrows, Escape, outside dismissal and focus restoration. Material owns tokens, geometry and motion.
Menu<T extends object>({ trigger, isOpen, defaultOpen, onOpenChange, placement, offset, crossOffset, className, style, popoverClassName, ...menuProps }: MenuProps<T>): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
className | string | undefined | — | — | @m3-ui/ui |
crossOffset | number | undefined | 0 | — | @m3-ui/ui |
defaultOpen | boolean | undefined | — | — | @m3-ui/ui |
isOpen | boolean | undefined | — | — | @m3-ui/ui |
offset | number | undefined | 4 | — | @m3-ui/ui |
onOpenChange | ((isOpen: boolean) => void) | undefined | — | — | @m3-ui/ui |
placement | Placement | undefined | 'bottom start' | — | @m3-ui/ui |
popoverClassName | string | undefined | — | — | @m3-ui/ui |
style | CSSProperties | undefined | — | — | @m3-ui/ui |
trigger* | ReactElement<unknown, string | JSXElementConstructor<any>> | — | — | @m3-ui/ui |
Inherited React / web props (92)
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-describedby | string | undefined | — | Identifies the element (or elements) that describes the object. | @react-types/shared |
aria-details | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. | @react-types/shared |
aria-label | string | undefined | — | Defines a string value that labels the current element. | @react-types/shared |
aria-labelledby | string | undefined | — | Identifies the element (or elements) that labels the current element. | @react-types/shared |
autoFocus | boolean | FocusStrategy | undefined | — | Where the focus should be set. | react-aria |
children | React.ReactNode | ((item: T) => ReactNode) | — | The contents of the collection. | react-aria-components |
defaultSelectedKeys | "all" | Iterable<Key> | undefined | — | The initial selected keys in the collection (uncontrolled). | @react-types/shared |
dependencies | readonly any[] | undefined | — | Values that should invalidate the item cache when using dynamic collections. | react-aria-components |
dir | string | undefined | — | — | @react-types/shared |
disabledKeys | Iterable<Key> | undefined | — | The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. | @react-types/shared |
disallowEmptySelection | boolean | undefined | — | Whether the collection allows empty selection. | @react-types/shared |
escapeKeyBehavior | "none" | "clearSelection" | undefined | 'clearSelection' | Whether pressing the escape key should clear selection in the menu or not. Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually. | react-aria |
hidden | boolean | undefined | — | — | @react-types/shared |
id | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | @react-types/shared |
inert | boolean | undefined | — | — | @react-types/shared |
items | Iterable<T> | undefined | — | Item objects in the collection. | @react-types/shared |
lang | string | undefined | — | — | @react-types/shared |
onAction | ((key: Key, value: T) => void) | undefined | — | Handler that is called when an item is selected. | react-aria |
onAnimationEnd | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationEndCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIteration | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIterationCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStart | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStartCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onClose | (() => void) | undefined | — | Handler that is called when the menu should close after selecting an item. | react-aria |
onContextMenu | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenuCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDown | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDownCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseEnter | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseLeave | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMove | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMoveCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOut | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOutCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOver | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOverCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUp | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUpCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancel | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancelCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDown | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDownCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerEnter | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerLeave | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMove | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMoveCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOut | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOutCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOver | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOverCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUp | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUpCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScroll | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScrollCapture | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onSelectionChange | ((keys: Selection) => void) | undefined | — | Handler that is called when the selection changes. | @react-types/shared |
onTouchCancel | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancelCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEnd | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEndCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMove | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMoveCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStart | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStartCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancel | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancelCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEnd | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEndCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRun | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRunCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStart | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStartCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheel | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheelCapture | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
render | DOMRenderFunction<"div", MenuRenderProps> | undefined | — | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. | react-aria-components |
renderEmptyState | (() => ReactNode) | undefined | — | Provides content to display when there are no items in the menu. | react-aria-components |
selectedKeys | "all" | Iterable<Key> | undefined | — | The currently selected keys in the collection (controlled). | @react-types/shared |
selectionMode | SelectionMode | undefined | — | The type of selection that is allowed in the collection. | @react-types/shared |
shouldCloseOnSelect | boolean | undefined | — | Whether the menu should close when the menu item is selected. | react-aria-components |
shouldFocusWrap | boolean | undefined | — | Whether keyboard navigation is circular. | react-aria |
slot | string | null | undefined | — | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. | react-aria-components |
translate | "yes" | "no" | undefined | — | — | @react-types/shared |
Source: packages/ui/src/components/Menu/Menu.tsx:55
ExposedDropdownMenu
ExposedDropdownMenu<T = unknown>({ items, value, onSelectionChange, isOpen, onOpenChange, inputValue, onInputChange, isDisabled, isReadOnly: readOnlyProp, matchAnchorWidth, variant, label, description, supportingText, errorMessage, placeholder, name, isRequired, className, style, secondaryTrigger, secondaryTriggerLabel, renderItem, renderAnchor, "aria-label": ariaLabel, }: ExposedDropdownMenuProps<T>): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-label | string | undefined | — | — | @m3-ui/ui |
className | string | undefined | — | — | @m3-ui/ui |
description | ReactNode | — | — | @m3-ui/ui |
errorMessage | ReactNode | — | — | @m3-ui/ui |
inputValue | string | undefined | — | — | @m3-ui/ui |
isDisabled | boolean | undefined | false | — | @m3-ui/ui |
isOpen* | boolean | — | — | @m3-ui/ui |
isReadOnly | boolean | undefined | — | — | @m3-ui/ui |
isRequired | boolean | undefined | — | — | @m3-ui/ui |
items* | readonly ExposedDropdownMenuItem<T>[] | — | — | @m3-ui/ui |
label | ReactNode | — | — | @m3-ui/ui |
matchAnchorWidth | boolean | undefined | menuRuntime.exposedMatchAnchorWidth | — | @m3-ui/ui |
name | string | undefined | — | — | @m3-ui/ui |
onInputChange | ((value: string) => void) | undefined | — | — | @m3-ui/ui |
onOpenChange* | (isOpen: boolean) => void | — | — | @m3-ui/ui |
onSelectionChange* | (value: string, item: ExposedDropdownMenuItem<T>) => void | — | — | @m3-ui/ui |
placeholder | string | undefined | — | — | @m3-ui/ui |
renderAnchor | ((props: ExposedDropdownMenuAnchorRenderProps) => ReactNode) | undefined | — | — | @m3-ui/ui |
renderItem | ((item: ExposedDropdownMenuItem<T>, state: ExposedDropdownMenuItemRenderState) => ReactNode) | undefined | — | — | @m3-ui/ui |
secondaryTrigger | ReactNode | — | — | @m3-ui/ui |
secondaryTriggerLabel | string | undefined | 'Toggle options' | — | @m3-ui/ui |
style | CSSProperties | undefined | — | — | @m3-ui/ui |
supportingText | ReactNode | — | — | @m3-ui/ui |
value* | string | — | — | @m3-ui/ui |
variant | "filled" | "outlined" | undefined | 'filled' | — | @m3-ui/ui |
Source: packages/ui/src/components/ExposedDropdownMenu/ExposedDropdownMenu.tsx:230
Material fidelity and web adaptation
- Family
- Menus
- Provenance
- spec: Material 3 overview · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- DropdownMenu · DropdownMenuItem · SelectableDropdownMenuItem · CheckableDropdownMenuItem · DropdownMenuGroup · cascading submenu composition · ExposedMenu read-only selection · ExposedDropdownMenu editable/read-only combobox and listbox selection
- Visual fidelity
- aligned: Reviewed action, selectable/checkable, segmented/vibrant group, submenu, and exposed-menu surfaces use audited Material geometry, roles, states, elevation, and color treatment.
- Behavior fidelity
- adapted: React Aria owns menu/menuitem/menuitemradio/menuitemcheckbox semantics, selection state, roving focus, Arrow/Home/End movement, typeahead, logical-direction submenu disclosure, Escape, outside dismissal, overlay positioning, and focus restoration. MenuSubmenu maps Material cascading-menu presentation onto React Aria SubmenuTrigger rather than duplicating its focus or keyboard engine. ExposedMenu is a React Aria MenuTrigger/Button rendered with the Material filled TextField presentation, so React Aria also owns trigger press/keyboard/open/focus and aria-haspopup/expanded behavior. ExposedDropdownMenu is a separate browser-native combobox/listbox mapping: it can be editable or read-only, keeps text editing on the input, and leaves filtering/query policy to application code.
- Semantics fidelity
- adapted: React Aria owns menu/menuitem/menuitemradio/menuitemcheckbox semantics, selection state, roving focus, Arrow/Home/End movement, typeahead, logical-direction submenu disclosure, Escape, outside dismissal, overlay positioning, and focus restoration. MenuSubmenu maps Material cascading-menu presentation onto React Aria SubmenuTrigger rather than duplicating its focus or keyboard engine. ExposedMenu is a React Aria MenuTrigger/Button rendered with the Material filled TextField presentation, so React Aria also owns trigger press/keyboard/open/focus and aria-haspopup/expanded behavior. ExposedDropdownMenu is a separate browser-native combobox/listbox mapping: it can be editable or read-only, keeps text editing on the input, and leaves filtering/query policy to application code.
- Adaptations
- React Aria owns menu/menuitem/menuitemradio/menuitemcheckbox semantics, selection state, roving focus, Arrow/Home/End movement, typeahead, logical-direction submenu disclosure, Escape, outside dismissal, overlay positioning, and focus restoration. MenuSubmenu maps Material cascading-menu presentation onto React Aria SubmenuTrigger rather than duplicating its focus or keyboard engine. ExposedMenu is a React Aria MenuTrigger/Button rendered with the Material filled TextField presentation, so React Aria also owns trigger press/keyboard/open/focus and aria-haspopup/expanded behavior. ExposedDropdownMenu is a separate browser-native combobox/listbox mapping: it can be editable or read-only, keeps text editing on the input, and leaves filtering/query policy to application code.
Material supplies surface, anatomy, spacing, state presentation, and visual hierarchy. React Aria supplies menu/menuitem focus, keyboard, popup positioning, dismissal, and restoration semantics. ExposedMenu is the deliberate read-only menu composition; ExposedDropdownMenu separately maps exposed selection to browser combobox/listbox semantics and supports editable or read-only input behavior.
Related components
- Text field — editable text input.
- Search bar — editable search input/results.
- List item — persistent content/action/selection rows.