No Preview

Sorry, but you either have no stories or none are selected somehow.

If the problem persists, check the browser console, or the terminal you've run Storybook from.

Menu
A menu displays a list of actions. The Menu component handles the
state management of the passed in list of actions.
Best Practices

Do
  • Use MenuTrigger as the first child of Menu.
  • Use MenuList as the only child of MenuPopover.
  • Create nested menus as separate components.
  • Use the hasIcons prop for alignment if only some menu items have icons.
  • Use the hasCheckmarks prop for alignment if only some menu items are selectable.
Don't
  • Don't render focusable or clickable items inside menu items.
  • Don't use more than 2 levels of nested menus.
  • Don't use verbose secondary content for menuitems.
  • Don't mix checkboxes and radio items without MenuGroup.
Default
Open in CodeSandbox
NameDescriptionDefaultControl 
onCheckedValueChange
Callback when checked items change for value with a name
((e: MenuCheckedValueChangeEvent, data: MenuCheckedValueChangeData) => void)
eventReact's original SyntheticEvent
dataA data object with relevant information
--
checkedValues
Map of all checked values
Record<string, string[]>
-
defaultCheckedValues
Default values to be checked on mount
Record<string, string[]>
-
hasIcons
States that menu items can contain icons and reserve slots for item alignment
boolean
-
hasCheckmarks
States that menu items can contain selectable items and reserve slots for item alignment
boolean
-
open
Whether the popup is open
boolean
-
onOpenChange
Call back when the component requests to change value
The open value is used as a hint when directly controlling the component
((e: MenuOpenEvents, data: MenuOpenChangeData) => void)
--
defaultOpen
Whether the popup is open by default
boolean
-
openOnHover
boolean
-
openOnContext
Opens the menu on right click (context menu), removes all other menu open interactions
boolean
-
inline
Root menus are rendered out of DOM order on document.body, use this to render the menu in DOM order
This option is disregarded for submenus
boolean
-
persistOnItemClick
Do not dismiss the menu when a menu item is clicked
boolean
-
hoverDelay
Sets the delay for mouse open/close for the popover one mouse enter/leave
number
-
children
Can contain two children including {@link MenuTrigger} and {@link MenuPopover}.
Alternatively can only contain {@link MenuPopover} if using a custom target.
(Element | [Element, Element]) & ReactNode
-
positioning
Configures the positioned menu
PositioningShorthand
-
Stories
Interaction
Each sub component of the Menu that renders DOM elements can be assigned HTML event listeners.
You can simply add an onClick listener to individual MenuItem without needing to control the entire
component. Special handling is required for checkboxes and radio items inside a Menu, read the further
examples below to see how to handle those variants.
Open in CodeSandbox
Open in CodeSandbox
Aligning With Icons
The hasIcons prop will align menu items if only a subset of menu items contain an icon.
When separation of menu items is only for visual aesthetics, the MenuDivider component can be used
by itself as it has no accessible markup features.
Open in CodeSandbox
Aligning With Selectable Items
The hasCheckmarks prop will align menu items if only a subset of menu items are selectable.
Open in CodeSandbox
Secondary Content For Menu Items
Open in CodeSandbox
Controlling Open And Close
The opening and close of the Menu can be controlled with your own state.
The onOpenChange callback will provide the hints for the state and triggers based on the appropriate
event.
When controlling the open state of the Menu, extra effort is required to ensure that interactions are
still appropriate and that keyboard accessibility does not degrade.
Open in CodeSandbox
Groupping Items
A menu can be divided in to separate groups, using the MenuGroup and MenuGroupHeader
components. This ensures the correct accessible markup is rendered for screen reader users.
Open in CodeSandbox
Visual Divider Only
If a divider is needed only for visual aesthetics, the MenuDivider component can be used separately.
When items should be logically groupped, use the MenuGroup and MenuGroupHeader components
for correct accessible markup.
Open in CodeSandbox
Checkbox Items
A variant of MenuItem that handles checkbox like selection. The name and value props are are used
similar to HTML checkboxes with input
<input type="checkbox" name="name" value="value" />
Open in CodeSandbox
Radio Items
A variant of MenuItem that handles radio like selection. The name and value props are are used
similar to HTML checkboxes with input
<input type="radio" name="name" value="value" />
Open in CodeSandbox
Controlled Checkbox Items
Open in CodeSandbox
Controlled Radio Items
Open in CodeSandbox
Selection Group
Both menu item checkboxes and radio items can be used in the same menu surface.
Different selection areas should be grouped to provide clear expectations for users.
Open in CodeSandbox
Nested Submenus
Menus can be nested within each other to render application submenus.
Submenus are a complex control for any app, make sure you need them.
  • Try and limit nesting to 2 levels.
  • Creating submenus as separate components will result in more maintainable code.
Open in CodeSandbox
Nested Submenus Controlled
Menus can be nested within each other to render application submenus.
Submenus are a complex control for any app, make sure you need them.
  • Try and limit nesting to 2 levels.
  • Creating submenus as separate components will result in more maintainable code.
Open in CodeSandbox
Anchor To Custom Target
A Menu can be used without a trigger and anchored to any DOM element. This can be useful if
a Menu instance needs to be reused in different places.
Not using a MenuTrigger will require more work to make sure your scenario is accessible
such as implementing accessible markup and keyboard interactions for your trigger
Open in CodeSandbox
Custom Trigger
Native elements and Fluent components have first class support as children of MenuTrigger
so they will be injected automatically with the correct props for interactions and accessibility attributes.
It is possible to use your own custom React component as a child of MenuTrigger. These components should
use ref forwarding with React.forwardRef
Open in CodeSandbox
Render Function Trigger
When a function is passed as the children of MenuTrigger, the actual trigger can be customized to be an
inner part of the function.
Open in CodeSandbox
Memoized Menu Items
⚠️ Rerendering menu items is a cheap operation and React philosophy encourages rerenders.
Memoization is not free, so use it only when there are concrete benefits to doing so.
Memoized menu items can be created using React.memo
to optimize rerenders of menu items if their props have not changed. Can be useful for selectable items,
since each selection will rerender all items in the menu by default.
Open in CodeSandbox
Split Menu Item
A menu item can be split into a main action and a trigger that opens a submenu.
Use this pattern sparingly. Make sure to add an aria-label to the trigger for screen reader users.
Open in CodeSandbox
A trigger for Menu can also have a tooltip.
Open in CodeSandbox