Menu
Flexible component for constructing dynamic and customizable menus.
The <Menu> component allows you to define a menu element. It's useful when you want a list with options or actions.
It is structured in two parts <Menu> and <Menu.Item>. The <Menu> contains the trigger and the button per default. You also can use the <Menu.Section> which you can use to separate the menu items from each other.
There is also a companion component called <ActionMenu> which you can use if you want to take some actions. You can have a look on how it works in the examples. It works quiet similar to the normal <Menu> component. All you have to add are the <Menu.Item>s.
Anatomy
-
Menu trigger: The element, such as a button or icon, that opens or activates the menu.
-
Section: Menus are made up of a section or multiple sections.
-
Section header: Contains a heading to name a section of a group of similar menu items.
-
Menu item: Represent an individual option or action within a Menu component.
Appearance
The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.
Variant
Size
| Property | Type | Description |
|---|---|---|
variant | secondary | ghost | The available variants of this component. |
size | default | small | large | icon | The available sizes of this component. |
Usage
In general, Menus are used to hide less frequently used or advanced options until users specifically need them. This keeps the interface clean and focused on essential elements.
Menus are ideal for interactive UI elements, it is distincit from <Select>, which is meant for form inputs and value selection.
Menus can speed up interactions for advanced users who are already familiar with the application. These users often rely on shortcuts and context-specific actions to work more efficiently.
Do
Write menu label that is clear, concise (max. 24 characters) and avoid unnecessary verbs.
Do
Organise your menu items based on priority, and put the most used items at the start of the menu.
Simple Menu with Action
In this example you can see a simple <Menu> with some items to select. it is used when you need a to provide users with a set of of options that will result in a specific action being performed.
Preview
Code
Menu with Sections
When you have mutliple menu items that can be categorized under different headings. This is particularly useful in complext menus with many options, you can use <Menu.Section> and pass title for the group name.
Preview
Code
Disabled Menu Items
In this example the <Menu> has set its prop disabeldKeys. So you can't interact with the <Menu.Item> anymore. Keep in mind, that you have to set an id to the <Menu.Item>.
Preview
Code
ActionMenu
The <ActionMenu> is typically used to provide quick, context-specific actions related to an item or interface element. It is particularly useful in scenarios where speed and efficiency in selecting an action are crucial.
In this example, the <ActionMenu> is used within a table to allow users to perform actions like viewing details of a ticket or deleting a ticket. When "View Details" is selected, a dialog displays key information about the selected ticket, including its ID, event name, and status. The "Delete" option removes the ticket from the list.
The example shows that the <ActionMenu> is very similar to the standard <Menu> component, offering flexibility and ease of use in various contexts.
Preview
Code
| ID | Event Name | Status | Action |
|---|---|---|---|
| TCK-001 | Champions League Final | Confirmed | |
| TCK-002 | Rock Concert | Pending | |
| TCK-003 | Broadway Show | Cancelled |
Menu with onOpenChange property
Here you can see how the properties open and onOpenChange are used together with a <Button>. A function handles the state for the menu. You just can open the <Menu> with the external <Button> component, not with the menu button.
A common use Case is also to open the <Menu> with the keyboard.
Preview
Code
Menu item opens Dialog
This Example shows how to open a <Dialog> from a <Menu.Item>. It is useful when a menu action requires additional user input or confirmation. Selecting the item opens a Dialog where users can provide the necessary information or confirm their choice, making the interaction smooth and efficient.
Preview
Code
Menu selection mode
Use multiple selection mode when you want to allow users to select multiple options at once, providing flexibility in situations where multiple choices are valid and necessary.
Here you can see how the selectionMode from <Menu> works. In this example the selectionMode is set to multiple. If you open the items you can see a selected item.
Preview
Code
Your preferences are : newsletter
Props
Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!
Menu
aria-describedby?string;
Identifies the element (or elements) that describes the object.
aria-details?string;
Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-label?string;
Defines a string value that labels the current element.
aria-labelledby?string;
Identifies the element (or elements) that labels the current element.
autoFocus?boolean | FocusStrategy;
Where the focus should be set.
children?ReactNode;
The contents of the menu.
defaultOpen?boolean;
Whether the overlay is open by default (uncontrolled).
defaultSelectedKeys?Iterable<Key> | "all";
The initial selected keys in the collection (uncontrolled).
dependencies?readonly any[]Values that should invalidate the item cache when using dynamic collections.
dir?string;
disabled?boolean;
Whether the menu trigger is disabled.
disabledKeys?Iterable<Key>;
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
disallowEmptySelection?boolean;
Whether the collection allows empty selection.
escapeKeyBehavior?"clearSelection" | "none";
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.
Defaults to:
'clearSelection'hidden?boolean;
id?string;
The element's unique identifier. See MDN.
inert?boolean;
items?Iterable<object>;
Item objects in the collection.
label?ReactNode;
The label for the menu trigger button.
lang?string;
onAction?(key: Key) => void;
Handler that is called when an action is performed on an item.
onAnimationEnd?AnimationEventHandler<HTMLDivElement>;
onAnimationEndCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationIteration?AnimationEventHandler<HTMLDivElement>;
onAnimationIterationCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationStart?AnimationEventHandler<HTMLDivElement>;
onAnimationStartCapture?AnimationEventHandler<HTMLDivElement>;
onAuxClick?MouseEventHandler<HTMLDivElement>;
onAuxClickCapture?MouseEventHandler<HTMLDivElement>;
onClick?MouseEventHandler<HTMLDivElement>;
onClickCapture?MouseEventHandler<HTMLDivElement>;
onClose?() => void;
Handler that is called when the menu should close after selecting an item.
onContextMenu?MouseEventHandler<HTMLDivElement>;
onContextMenuCapture?MouseEventHandler<HTMLDivElement>;
onDoubleClick?MouseEventHandler<HTMLDivElement>;
onDoubleClickCapture?MouseEventHandler<HTMLDivElement>;
onGotPointerCapture?PointerEventHandler<HTMLDivElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onLostPointerCapture?PointerEventHandler<HTMLDivElement>;
onLostPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onMouseDown?MouseEventHandler<HTMLDivElement>;
onMouseDownCapture?MouseEventHandler<HTMLDivElement>;
onMouseEnter?MouseEventHandler<HTMLDivElement>;
onMouseLeave?MouseEventHandler<HTMLDivElement>;
onMouseMove?MouseEventHandler<HTMLDivElement>;
onMouseMoveCapture?MouseEventHandler<HTMLDivElement>;
onMouseOut?MouseEventHandler<HTMLDivElement>;
onMouseOutCapture?MouseEventHandler<HTMLDivElement>;
onMouseOver?MouseEventHandler<HTMLDivElement>;
onMouseOverCapture?MouseEventHandler<HTMLDivElement>;
onMouseUp?MouseEventHandler<HTMLDivElement>;
onMouseUpCapture?MouseEventHandler<HTMLDivElement>;
onOpenChange?(isOpen: boolean) => void;
Handler that is called when the overlay's open state changes.
onPointerCancel?PointerEventHandler<HTMLDivElement>;
onPointerCancelCapture?PointerEventHandler<HTMLDivElement>;
onPointerDown?PointerEventHandler<HTMLDivElement>;
onPointerDownCapture?PointerEventHandler<HTMLDivElement>;
onPointerEnter?PointerEventHandler<HTMLDivElement>;
onPointerLeave?PointerEventHandler<HTMLDivElement>;
onPointerMove?PointerEventHandler<HTMLDivElement>;
onPointerMoveCapture?PointerEventHandler<HTMLDivElement>;
onPointerOut?PointerEventHandler<HTMLDivElement>;
onPointerOutCapture?PointerEventHandler<HTMLDivElement>;
onPointerOver?PointerEventHandler<HTMLDivElement>;
onPointerOverCapture?PointerEventHandler<HTMLDivElement>;
onPointerUp?PointerEventHandler<HTMLDivElement>;
onPointerUpCapture?PointerEventHandler<HTMLDivElement>;
onScroll?UIEventHandler<HTMLDivElement>;
onScrollCapture?UIEventHandler<HTMLDivElement>;
onSelectionChange?(keys: Selection) => void;
Handler that is called when the selection changes.
onTouchCancel?TouchEventHandler<HTMLDivElement>;
onTouchCancelCapture?TouchEventHandler<HTMLDivElement>;
onTouchEnd?TouchEventHandler<HTMLDivElement>;
onTouchEndCapture?TouchEventHandler<HTMLDivElement>;
onTouchMove?TouchEventHandler<HTMLDivElement>;
onTouchMoveCapture?TouchEventHandler<HTMLDivElement>;
onTouchStart?TouchEventHandler<HTMLDivElement>;
onTouchStartCapture?TouchEventHandler<HTMLDivElement>;
onTransitionCancel?TransitionEventHandler<HTMLDivElement>;
onTransitionCancelCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionEnd?TransitionEventHandler<HTMLDivElement>;
onTransitionEndCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionRun?TransitionEventHandler<HTMLDivElement>;
onTransitionRunCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionStart?TransitionEventHandler<HTMLDivElement>;
onTransitionStartCapture?TransitionEventHandler<HTMLDivElement>;
onWheel?WheelEventHandler<HTMLDivElement>;
onWheelCapture?WheelEventHandler<HTMLDivElement>;
open?boolean;
Whether the menu is open.
Defaults to:
"false"placement?Placement;
Placement of the popover.
Defaults to:
'bottom'renderEmptyState?() => ReactNode;
Provides content to display when there are no items in the list.
selectedKeys?Iterable<Key> | "all";
The currently selected keys in the collection (controlled).
selectionMode?SelectionMode;
The type of selection that is allowed in the collection.
shouldFocusWrap?boolean;
Whether keyboard navigation is circular.
slot?string | null;
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.translate?"yes" | "no";
trigger?MenuTriggerType;
How the menu is triggered.
Defaults to:
'press'Menu.Item
aria-label?string;
An accessibility label for this item.
children?ChildrenOrFunction<MenuItemRenderProps>;
The children of the component. A function may be provided to alter the children based on component state.
dir?string;
download?string | boolean;
Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
hidden?boolean;
href?string;
A URL to link to. See MDN.
hrefLang?string;
Hints at the human language of the linked URL. SeeMDN.
id?Key;
The unique id of the item.
inert?boolean;
isDisabled?boolean;
Whether the item is disabled.
lang?string;
onAction?() => void;
Handler that is called when the item is selected.
onAnimationEnd?AnimationEventHandler<HTMLDivElement>;
onAnimationEndCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationIteration?AnimationEventHandler<HTMLDivElement>;
onAnimationIterationCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationStart?AnimationEventHandler<HTMLDivElement>;
onAnimationStartCapture?AnimationEventHandler<HTMLDivElement>;
onAuxClick?MouseEventHandler<HTMLDivElement>;
onAuxClickCapture?MouseEventHandler<HTMLDivElement>;
onClick?(e: MouseEvent<FocusableElement, MouseEvent>) => void;
Not recommended – use
onPress instead. onClick is an alias for onPress
provided for compatibility with other libraries. onPress provides
additional event details for non-mouse interactions.onClickCapture?MouseEventHandler<HTMLDivElement>;
onContextMenu?MouseEventHandler<HTMLDivElement>;
onContextMenuCapture?MouseEventHandler<HTMLDivElement>;
onDoubleClick?MouseEventHandler<HTMLDivElement>;
onDoubleClickCapture?MouseEventHandler<HTMLDivElement>;
onGotPointerCapture?PointerEventHandler<HTMLDivElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onHoverChange?(isHovering: boolean) => void;
Handler that is called when the hover state changes.
onHoverEnd?(e: HoverEvent) => void;
Handler that is called when a hover interaction ends.
onHoverStart?(e: HoverEvent) => void;
Handler that is called when a hover interaction starts.
onLostPointerCapture?PointerEventHandler<HTMLDivElement>;
onLostPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onMouseDown?MouseEventHandler<HTMLDivElement>;
onMouseDownCapture?MouseEventHandler<HTMLDivElement>;
onMouseEnter?MouseEventHandler<HTMLDivElement>;
onMouseLeave?MouseEventHandler<HTMLDivElement>;
onMouseMove?MouseEventHandler<HTMLDivElement>;
onMouseMoveCapture?MouseEventHandler<HTMLDivElement>;
onMouseOut?MouseEventHandler<HTMLDivElement>;
onMouseOutCapture?MouseEventHandler<HTMLDivElement>;
onMouseOver?MouseEventHandler<HTMLDivElement>;
onMouseOverCapture?MouseEventHandler<HTMLDivElement>;
onMouseUp?MouseEventHandler<HTMLDivElement>;
onMouseUpCapture?MouseEventHandler<HTMLDivElement>;
onPointerCancel?PointerEventHandler<HTMLDivElement>;
onPointerCancelCapture?PointerEventHandler<HTMLDivElement>;
onPointerDown?PointerEventHandler<HTMLDivElement>;
onPointerDownCapture?PointerEventHandler<HTMLDivElement>;
onPointerEnter?PointerEventHandler<HTMLDivElement>;
onPointerLeave?PointerEventHandler<HTMLDivElement>;
onPointerMove?PointerEventHandler<HTMLDivElement>;
onPointerMoveCapture?PointerEventHandler<HTMLDivElement>;
onPointerOut?PointerEventHandler<HTMLDivElement>;
onPointerOutCapture?PointerEventHandler<HTMLDivElement>;
onPointerOver?PointerEventHandler<HTMLDivElement>;
onPointerOverCapture?PointerEventHandler<HTMLDivElement>;
onPointerUp?PointerEventHandler<HTMLDivElement>;
onPointerUpCapture?PointerEventHandler<HTMLDivElement>;
onPress?(e: PressEvent) => void;
Handler that is called when the press is released over the target.
onPressChange?(isPressed: boolean) => void;
Handler that is called when the press state changes.
onPressEnd?(e: PressEvent) => void;
Handler that is called when a press interaction ends, either
over the target or when the pointer leaves the target.
onPressStart?(e: PressEvent) => void;
Handler that is called when a press interaction starts.
onPressUp?(e: PressEvent) => void;
Handler that is called when a press is released over the target, regardless of
whether it started on the target or not.
onScroll?UIEventHandler<HTMLDivElement>;
onScrollCapture?UIEventHandler<HTMLDivElement>;
onTouchCancel?TouchEventHandler<HTMLDivElement>;
onTouchCancelCapture?TouchEventHandler<HTMLDivElement>;
onTouchEnd?TouchEventHandler<HTMLDivElement>;
onTouchEndCapture?TouchEventHandler<HTMLDivElement>;
onTouchMove?TouchEventHandler<HTMLDivElement>;
onTouchMoveCapture?TouchEventHandler<HTMLDivElement>;
onTouchStart?TouchEventHandler<HTMLDivElement>;
onTouchStartCapture?TouchEventHandler<HTMLDivElement>;
onTransitionCancel?TransitionEventHandler<HTMLDivElement>;
onTransitionCancelCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionEnd?TransitionEventHandler<HTMLDivElement>;
onTransitionEndCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionRun?TransitionEventHandler<HTMLDivElement>;
onTransitionRunCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionStart?TransitionEventHandler<HTMLDivElement>;
onTransitionStartCapture?TransitionEventHandler<HTMLDivElement>;
onWheel?WheelEventHandler<HTMLDivElement>;
onWheelCapture?WheelEventHandler<HTMLDivElement>;
ping?string;
A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy?HTMLAttributeReferrerPolicy;
How much of the referrer to send when following the link. See MDN.
rel?string;
The relationship between the linked resource and the current page. See MDN.
routerOptions?undefined;
Options for the configured client side router.
target?HTMLAttributeAnchorTarget;
The target window for the link. See MDN.
textValue?string;
A string representation of the item's contents, used for features like typeahead.
translate?"yes" | "no";
value?object;
The object value that this item represents. When using dynamic collections, this is set automatically.
Menu.Section
aria-label?string;
An accessibility label for the section.
childrenReactNode;
dependencies?readonly any[]Values that should invalidate the item cache when using dynamic collections.
dir?string;
hidden?boolean;
id?Key;
The unique id of the section.
inert?boolean;
items?Iterable<object>;
Item objects in the section.
lang?string;
onAnimationEnd?AnimationEventHandler<HTMLElement>;
onAnimationEndCapture?AnimationEventHandler<HTMLElement>;
onAnimationIteration?AnimationEventHandler<HTMLElement>;
onAnimationIterationCapture?AnimationEventHandler<HTMLElement>;
onAnimationStart?AnimationEventHandler<HTMLElement>;
onAnimationStartCapture?AnimationEventHandler<HTMLElement>;
onAuxClick?MouseEventHandler<HTMLElement>;
onAuxClickCapture?MouseEventHandler<HTMLElement>;
onClick?MouseEventHandler<HTMLElement>;
onClickCapture?MouseEventHandler<HTMLElement>;
onContextMenu?MouseEventHandler<HTMLElement>;
onContextMenuCapture?MouseEventHandler<HTMLElement>;
onDoubleClick?MouseEventHandler<HTMLElement>;
onDoubleClickCapture?MouseEventHandler<HTMLElement>;
onGotPointerCapture?PointerEventHandler<HTMLElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLElement>;
onLostPointerCapture?PointerEventHandler<HTMLElement>;
onLostPointerCaptureCapture?PointerEventHandler<HTMLElement>;
onMouseDown?MouseEventHandler<HTMLElement>;
onMouseDownCapture?MouseEventHandler<HTMLElement>;
onMouseEnter?MouseEventHandler<HTMLElement>;
onMouseLeave?MouseEventHandler<HTMLElement>;
onMouseMove?MouseEventHandler<HTMLElement>;
onMouseMoveCapture?MouseEventHandler<HTMLElement>;
onMouseOut?MouseEventHandler<HTMLElement>;
onMouseOutCapture?MouseEventHandler<HTMLElement>;
onMouseOver?MouseEventHandler<HTMLElement>;
onMouseOverCapture?MouseEventHandler<HTMLElement>;
onMouseUp?MouseEventHandler<HTMLElement>;
onMouseUpCapture?MouseEventHandler<HTMLElement>;
onPointerCancel?PointerEventHandler<HTMLElement>;
onPointerCancelCapture?PointerEventHandler<HTMLElement>;
onPointerDown?PointerEventHandler<HTMLElement>;
onPointerDownCapture?PointerEventHandler<HTMLElement>;
onPointerEnter?PointerEventHandler<HTMLElement>;
onPointerLeave?PointerEventHandler<HTMLElement>;
onPointerMove?PointerEventHandler<HTMLElement>;
onPointerMoveCapture?PointerEventHandler<HTMLElement>;
onPointerOut?PointerEventHandler<HTMLElement>;
onPointerOutCapture?PointerEventHandler<HTMLElement>;
onPointerOver?PointerEventHandler<HTMLElement>;
onPointerOverCapture?PointerEventHandler<HTMLElement>;
onPointerUp?PointerEventHandler<HTMLElement>;
onPointerUpCapture?PointerEventHandler<HTMLElement>;
onScroll?UIEventHandler<HTMLElement>;
onScrollCapture?UIEventHandler<HTMLElement>;
onTouchCancel?TouchEventHandler<HTMLElement>;
onTouchCancelCapture?TouchEventHandler<HTMLElement>;
onTouchEnd?TouchEventHandler<HTMLElement>;
onTouchEndCapture?TouchEventHandler<HTMLElement>;
onTouchMove?TouchEventHandler<HTMLElement>;
onTouchMoveCapture?TouchEventHandler<HTMLElement>;
onTouchStart?TouchEventHandler<HTMLElement>;
onTouchStartCapture?TouchEventHandler<HTMLElement>;
onTransitionCancel?TransitionEventHandler<HTMLElement>;
onTransitionCancelCapture?TransitionEventHandler<HTMLElement>;
onTransitionEnd?TransitionEventHandler<HTMLElement>;
onTransitionEndCapture?TransitionEventHandler<HTMLElement>;
onTransitionRun?TransitionEventHandler<HTMLElement>;
onTransitionRunCapture?TransitionEventHandler<HTMLElement>;
onTransitionStart?TransitionEventHandler<HTMLElement>;
onTransitionStartCapture?TransitionEventHandler<HTMLElement>;
onWheel?WheelEventHandler<HTMLElement>;
onWheelCapture?WheelEventHandler<HTMLElement>;
title?string;
translate?"yes" | "no";
value?object;
The object value that this section represents. When using dynamic collections, this is set automatically.
Last update: October 25, 2024