Can be 'start', 'center', or 'end'.

It sets alignment of menu with anchor element.

Sets aria-label attribute on the menu DOM element.

If not provided, one will be generated from the string content of menu button, or the default 'Menu'.

Set true to display an arrow pointing to its anchor element.

Properties of this object are spread to the menu arrow DOM element.

A string that will be appended to the class of menu arrow DOM element.

When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.

• dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.

Specify bounding box padding in pixels. Use a syntax similar to the CSS padding property but sizing units are discarded.

A ref object attached to a DOM element within which menu will be positioned. If not provided, the nearest ancestor which has CSS overflow set to a value other than 'visible' or the browser viewport will serve as the bounding box.

Supports ref created by React.createRef or useRef Hook, or an object of { current: { getBoundingClientRect(): DOMRect } }. Doesn't support callback ref.

Menu items underneath the menu, or a function that returns them. The function will be called by passing an object with the following properties:

• state: string indicates the state of menu. Can be 'opening', 'open', 'closing', 'closed'
• dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.

Properties of this object are spread to the root DOM element containing the menu.

Can be 'left', 'right', 'top', or 'bottom'.

It sets direction in which menu expands against anchor element.

Properties of this object are spread to a DOM element which captures focus for the menu.

Add a gap (gutter) between menu and its anchor element. The value (in pixels) can be negative.

By default menu isn't mounted into DOM until it's opened for the first time. Setting the prop to true will change this behaviour, which also enables menu and its items to be server rendered.

A ref which attaches to menu component and provides the follow methods:

• openMenu: (position?: 'first' | 'last' | number, alwaysUpdate?: boolean) => void open menu, optional request which menu item will be hovered.
• closeMenu: () => void close menu

Can be a MenuButton, a button element, or a React component.

It also accepts a function that returns one of the above. The function will be called by passing an object with the following properties:

• open: bool indicates if the menu is open.

If a React component is provided, it needs to implement the following contracts:

• Accepts a ref prop that is forwarded to the element to which menu will be positioned. The element should be able to receive focus.
• Accepts onClick and onKeyDown event props.

Please note MenuButton has one additional benefit that it has managed aria-haspopup and aria-expanded attributes. When using a button element or your own React component, it's your job to set these aria attributes if you need correct accessibility support.

A string that will be appended to the class of menu DOM element.

When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.

• state: string indicates the state of menu. Can be 'opening', 'open', 'closing', 'closed'
• dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.

This value is forwarded to the style prop of menu DOM element.

Event fired when descendent menu items are clicked.

Event object properties:

• value: any the value prop passed to the MenuItem being clicked. It's useful for helping identify which menu item is clicked.
• key: string indicates the key if click is triggered by keyboard. Can be 'Enter' or ' '(Space).
• checked: bool indicates if the menu item is checked, only for MenuItem type="checkbox".
• name: string the name prop passed to the MenuRadioGroup when the menu item is in a radio group.
• keepOpen: bool set this property on event object to control whether to keep menu open after menu item is activated. Leaving it undefined will behave in accordance with WAI-ARIA Authoring Practices. See a CodeSandbox example for its usage.
• stopPropagation: bool setting this property on event object to true will skip onItemClick event on root menu component.
• syntheticEvent: MouseEvent | KeyboardEvent DOM event object (React synthetic event)

Event fired when menu states have changed.

Event object properties:

• open: bool indicates if the menu is open.

Can be 'visible', 'auto', or 'hidden'.

It makes the menu list scrollable or hidden when there is not enough viewport space to display all menu items. The value is similar to the CSS overflow property.

boolean |
{
  target?: Element;
  stablePosition?: boolean;
}

If true, menu is rendered as a direct child of document.body, or you can specify a target element in the DOM as menu container.

• target specify a DOM node under which menu will be rendered.
• stablePosition when target is null, setting this value true prevents menu from rendering into the DOM hierarchy of its parent component.

Portal allows menu to visually “break out” of its container. Typical use cases may include:

• An ancestor container is positioned and CSS overflowis set to a value other than visible.
• You have a DOM structure that creates a complex hierarchy of stacking contexts, and menu is overlapped regardless of z-indexvalue.

Note: portal breaks tab sequence and may impact the accessibility of your website.

It sets the position of menu related to its anchor element.

• 'auto' menu position is adjusted to have it contained within the viewport, even if it will be detached from the anchor element. This option allows to display menu in the viewport as much as possible.
• 'anchor' menu position is adjusted to have it contained within the viewport, but it will be kept attached to the edges of anchor element.
• 'initial' menu always stays at its initial position.

It specifies when menu is repositioned.

• 'initial' Don't automatically reposition menu. Set to this value when you want to explicitly reposition menu using the repositionFlag prop.
• 'auto' Reposition menu whenever its size has changed, using the ResizeObserver API.

Use this prop to explicitly reposition menu. Whenever the prop has a new value, menu position will be recalculated and updated. You might use a counter and increase it every time.

Warning: don't update this prop in rapid succession, which is inefficient and might cause infinite rendering of component. E.g., don't change the value of this prop in window scroll event.

Set computed overflow amount down to a child MenuGroup. The MenuGroup should have takeOverflow prop set as true accordingly.

Shift menu's position away from its anchor element. The value (in pixels) can be negative.

Set a delay in ms before closing a submenu when it's open and mouse is moving over other items in the parent menu list.

Set a delay in ms before opening a submenu when mouse moves over it.

It sets a CSS class on the container element of menu for theming purpose. E.g., 'dark' will add szh-menu-container--theme-dark.

boolean |
{
  open?: boolean;
  close?: boolean;
  item?: boolean;
}

Enable or disable transition effects in the Menu,MenuItem, and any descendent SubMenu.

You can set 'open', 'close', 'item' at the same time with one boolean value or separately with an object.

If you enable transition on menu, make sure to add import '@szhsin/react-menu/dist/transitions/slide.css', or add your own animation styles, otherwise menu cannot be closed or have visible delay when closed.

A fallback timeout to stop transition if onAnimationEnd events are not fired.

By default menu remains in DOM when it's closed. Setting the prop to true will change this behaviour.

It sets the behaviour of menu and any of its descendent submenus when window is scrolling.

• 'initial' The window scroll event is ignored and has no effect on menu.
• 'auto' Menu will reposition itself based on the value of position prop when window is scrolling.
• 'close' menu will be closed when window is scrolled.

Set true if a checkbox menu item is checked. Please note radio menu item doesn't use this prop.

Contents of the menu item, or a function that returns it. The function will be called by passing an object with the following properties:

• hover: bool indicates if the menu item is being hovered and has focus.
• checked: bool indicates if the menu item is checked when it's a radio or checkbox item.
• disabled: bool indicates if the menu item is disabled.
• anchor: bool indicates if the menu item has a URL link.
• type: string 'radio' in radio item, 'checkbox' in checkbox item, or undefined in other items.

A string that will be appended to the class of menu item DOM element.

When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.

• hover: bool indicates if the menu item is being hovered and has focus.
• checked: bool indicates if the menu item is checked when it's a radio or checkbox item.
• disabled: bool indicates if the menu item is disabled.
• anchor: bool indicates if the menu item has a URL link.
• type: string 'radio' in radio item, 'checkbox' in checkbox item, or undefined in other items.

Set true to disable the menu item.

Event fired when the menu item is clicked.

Event object properties:

• value: any the value prop passed to the MenuItem being clicked. It's useful for helping identify which menu item is clicked.
• key: string indicates the key if click is triggered by keyboard. Can be 'Enter' or ' '(Space).
• checked: bool indicates if the menu item is checked, only for MenuItem type="checkbox".
• name: string the name prop passed to the MenuRadioGroup when the menu item is in a radio group.
• keepOpen: bool set this property on event object to control whether to keep menu open after menu item is activated. Leaving it undefined will behave in accordance with WAI-ARIA Authoring Practices. See a CodeSandbox example for its usage.
• stopPropagation: bool setting this property on event object to true will skip onItemClick event on root menu component.
• syntheticEvent: MouseEvent | KeyboardEvent DOM event object (React synthetic event)

Set this prop to 'checkbox' or 'radio' to make it a checkbox or radio menu item.

Any value provided to this prop will be available in the event object of click events.

It's useful for helping identify which menu item is clicked when you listen the onItemClick event on root menu component.

A string that will be appended to the class of menu button DOM element.

When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.

• open: bool indicates if the menu is open.

Set true to disable the menu button.

A function which returns what to be rendered. It will be called by passing an object with the following properties:

• hover: bool indicates if the focusable item is being hovered.
• disabled: bool indicates if the focusable item is disabled.
• ref: object A ref to be attached to the element which should receive focus when this focusable item is hovered.
  If you render a React component, it needs to expose a focus method or implement ref forwarding.
• closeMenu: func A function that requests to close the root menu. You could optionally pass a key parameter to indicate which key initiates the close request.

A string that will be appended to the class of focusable item DOM element.

When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.

• focusable: bool always true for a focusable item.
• hover: bool indicates if the focusable item is being hovered.
• disabled: bool indicates if the focusable item is disabled.

Set true to disable the item.

Please note this prop only removes the current item from mouse and keyboard interaction sequences. You still need to disable any focusable element which you have supplied in its children. This prop is passed to the children render function.

Can be 'start', 'center', or 'end'.

It sets alignment of menu with anchor element.

Sets aria-label attribute on the submenu DOM element.

If not provided, one will be generated from the string content of label prop, or the default 'Submenu'.

Set true to display an arrow pointing to its anchor element.

Properties of this object are spread to the menu arrow DOM element.

A string that will be appended to the class of menu arrow DOM element.

When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.

• dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.

Menu items underneath the menu, or a function that returns them. The function will be called by passing an object with the following properties:

• state: string indicates the state of menu. Can be 'opening', 'open', 'closing', 'closed'
• dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.

Can be 'left', 'right', 'top', or 'bottom'.

It sets direction in which menu expands against anchor element.

Set true to disable the submenu item (and the submenu).

Properties of this object are spread to a DOM element which captures focus for the menu.

Add a gap (gutter) between menu and its anchor element. The value (in pixels) can be negative.

A ref which attaches to menu component and provides the follow methods:

• openMenu: (position?: 'first' | 'last' | number, alwaysUpdate?: boolean) => void open menu, optional request which menu item will be hovered.
• closeMenu: () => void close menu

Properties of this object are spread to the submenu item DOM element.

A string that will be appended to the class of submenu item DOM element.

When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.

• open: bool indicates if the submenu is open.
• hover: bool indicates if the submenu item is being hovered and has focus.
• disabled: bool indicates if the submenu and item are disabled.

Contents of the submenu item, or a function that returns it. The function will be called by passing an object with the following properties:

• open: bool indicates if the submenu is open.
• hover: bool indicates if the submenu item is being hovered and has focus.
• disabled: bool indicates if the submenu and item are disabled.

A string that will be appended to the class of menu DOM element.

When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.

• state: string indicates the state of menu. Can be 'opening', 'open', 'closing', 'closed'
• dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.

This value is forwarded to the style prop of menu DOM element.

Event fired when menu states have changed.

Event object properties:

• open: bool indicates if the menu is open.

• undefined submenu opens when the label item is hovered or clicked. This is the default behaviour.
• 'clickOnly' submenu opens when the label item is clicked.
• 'none' submenu doesn't open with mouse or keyboard events; you can call the openMenu function on instanceRef to open submenu programmatically.

Can be 'visible', 'auto', or 'hidden'.

It makes the menu list scrollable or hidden when there is not enough viewport space to display all menu items. The value is similar to the CSS overflow property.

It sets the position of menu related to its anchor element.

• 'auto' menu position is adjusted to have it contained within the viewport, even if it will be detached from the anchor element. This option allows to display menu in the viewport as much as possible.
• 'anchor' menu position is adjusted to have it contained within the viewport, but it will be kept attached to the edges of anchor element.
• 'initial' menu always stays at its initial position.

Set computed overflow amount down to a child MenuGroup. The MenuGroup should have takeOverflow prop set as true accordingly.

Shift menu's position away from its anchor element. The value (in pixels) can be negative.

Sets aria-label attribute on the radio group DOM element.

If not provided, it will be set as the value of name prop, or the default 'Radio group'.

The only permitted children is MenuItem.

Sets the radio group name (optional).

The name will be passed to the onRadioChange event. It's useful for identifying radio groups if you attach the same event handler to multiple groups.

Event fired when a child menu item is clicked (selected).

Event object properties:

• name: string the name prop passed to the MenuRadioGroup on which this event occurred.
• value: any the value prop passed to the MenuItem being clicked.
• key: string indicates the key if click is triggered by keyboard. Can be 'Enter' or ' '(Space).
• keepOpen: bool set this property on event object to control whether to keep menu open after menu item is activated. Leaving it undefined will behave in accordance with WAI-ARIA Authoring Practices. See a CodeSandbox example for its usage.
• stopPropagation: bool setting this property on event object to true will skip onItemClick event on root menu component.
• syntheticEvent: MouseEvent | KeyboardEvent DOM event object (React synthetic event)

Sets value of the radio group.

The child menu item which has the same value (strict equality ===) as the radio group is marked as checked.

Set true to apply overflow of the parent menu to the group. Only one MenuGroup in a menu should set this prop as true.

Can be 'start', 'center', or 'end'.

It sets alignment of menu with anchor element.

Use this prop only for context menu. See an example.

An object describes viewport coordinates to which context menu will be positioned.

It's an object with the shape of { x: number, y: number }.

Not needed for context menu.

A ref object attached to a DOM element to which menu will be positioned.

Supports ref created by React.createRef or useRef Hook, or an object of { current: { getBoundingClientRect(): DOMRect } }. Doesn't support callback ref.

Sets aria-label attribute on the menu DOM element.

If not provided, it will be set as 'Menu'.

Set true to display an arrow pointing to its anchor element.

Properties of this object are spread to the menu arrow DOM element.

A string that will be appended to the class of menu arrow DOM element.

When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.

• dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.

Specify bounding box padding in pixels. Use a syntax similar to the CSS padding property but sizing units are discarded.

A ref object attached to a DOM element within which menu will be positioned. If not provided, the nearest ancestor which has CSS overflow set to a value other than 'visible' or the browser viewport will serve as the bounding box.

Supports ref created by React.createRef or useRef Hook, or an object of { current: { getBoundingClientRect(): DOMRect } }. Doesn't support callback ref.

If true, the menu list element will gain focus after menu is open.

Menu items underneath the menu, or a function that returns them. The function will be called by passing an object with the following properties:

• state: string indicates the state of menu. Can be 'opening', 'open', 'closing', 'closed'
• dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.

Properties of this object are spread to the root DOM element containing the menu.

Can be 'left', 'right', 'top', or 'bottom'.

It sets direction in which menu expands against anchor element.

Properties of this object are spread to a DOM element which captures focus for the menu.

Add a gap (gutter) between menu and its anchor element. The value (in pixels) can be negative.

By default menu isn't mounted into DOM until it's opened for the first time. Setting the prop to true will change this behaviour, which also enables menu and its items to be server rendered.

A string that will be appended to the class of menu DOM element.

When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.

• state: string indicates the state of menu. Can be 'opening', 'open', 'closing', 'closed'
• dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.

Sets which menu item receives focus (hover) when menu opens.

You will usually set this prop when the menu is opened by keyboard events.

It's an object with the shape of:

{
    position?: 'first' | 'last' | number;
    alwaysUpdate?: boolean;
}

The position can be one of the following values:

• 'first' focus the first item in the menu.
• 'last' focus the last item in the menu.
• number focus item at the specific position.

If you don't intend to update focus (hover) position, it's important to keep this prop's identity stable when your component re-renders.

This value is forwarded to the style prop of menu DOM element.

Event fired when menu is about to close.

Event object properties:

• reason: string the reason that causes the close event. Can be 'click', 'cancel', 'blur', or 'scroll'.
• value: any the value prop passed to the MenuItem being clicked.
• key: string indicates the key if event is triggered by keyboard. Can be 'Enter', ' '(Space) or 'Escape'.

Event fired when descendent menu items are clicked.

Event object properties:

• value: any the value prop passed to the MenuItem being clicked. It's useful for helping identify which menu item is clicked.
• key: string indicates the key if click is triggered by keyboard. Can be 'Enter' or ' '(Space).
• checked: bool indicates if the menu item is checked, only for MenuItem type="checkbox".
• name: string the name prop passed to the MenuRadioGroup when the menu item is in a radio group.
• keepOpen: bool set this property on event object to control whether to keep menu open after menu item is activated. Leaving it undefined will behave in accordance with WAI-ARIA Authoring Practices. See a CodeSandbox example for its usage.
• stopPropagation: bool setting this property on event object to true will skip onItemClick event on root menu component.
• syntheticEvent: MouseEvent | KeyboardEvent DOM event object (React synthetic event)

Can be 'visible', 'auto', or 'hidden'.

It makes the menu list scrollable or hidden when there is not enough viewport space to display all menu items. The value is similar to the CSS overflow property.

boolean |
{
  target?: Element;
  stablePosition?: boolean;
}

If true, menu is rendered as a direct child of document.body, or you can specify a target element in the DOM as menu container.

• target specify a DOM node under which menu will be rendered.
• stablePosition when target is null, setting this value true prevents menu from rendering into the DOM hierarchy of its parent component.

Portal allows menu to visually “break out” of its container. Typical use cases may include:

• An ancestor container is positioned and CSS overflowis set to a value other than visible.
• You have a DOM structure that creates a complex hierarchy of stacking contexts, and menu is overlapped regardless of z-indexvalue.

Note: portal breaks tab sequence and may impact the accessibility of your website.

It sets the position of menu related to its anchor element.

• 'auto' menu position is adjusted to have it contained within the viewport, even if it will be detached from the anchor element. This option allows to display menu in the viewport as much as possible.
• 'anchor' menu position is adjusted to have it contained within the viewport, but it will be kept attached to the edges of anchor element.
• 'initial' menu always stays at its initial position.

It specifies when menu is repositioned.

• 'initial' Don't automatically reposition menu. Set to this value when you want to explicitly reposition menu using the repositionFlag prop.
• 'auto' Reposition menu whenever its size has changed, using the ResizeObserver API.

Use this prop to explicitly reposition menu. Whenever the prop has a new value, menu position will be recalculated and updated. You might use a counter and increase it every time.

Warning: don't update this prop in rapid succession, which is inefficient and might cause infinite rendering of component. E.g., don't change the value of this prop in window scroll event.

Set computed overflow amount down to a child MenuGroup. The MenuGroup should have takeOverflow prop set as true accordingly.

Shift menu's position away from its anchor element. The value (in pixels) can be negative.

Controls the state of menu: 'opening' | 'open' | 'closing' | 'closed'. When the value is undefined, menu will be unmounted from DOM.

Set a delay in ms before closing a submenu when it's open and mouse is moving over other items in the parent menu list.

Set a delay in ms before opening a submenu when mouse moves over it.

It sets a CSS class on the container element of menu for theming purpose. E.g., 'dark' will add szh-menu-container--theme-dark.

boolean |
{
  open?: boolean;
  close?: boolean;
  item?: boolean;
}

Enable or disable transition effects in the Menu,MenuItem, and any descendent SubMenu.

You can set 'open', 'close', 'item' at the same time with one boolean value or separately with an object.

If you enable transition on menu, make sure to add import '@szhsin/react-menu/dist/transitions/slide.css', or add your own animation styles, otherwise menu cannot be closed or have visible delay when closed.

A fallback timeout to stop transition if onAnimationEnd events are not fired.

By default menu remains in DOM when it's closed. Setting the prop to true will change this behaviour.

It sets the behaviour of menu and any of its descendent submenus when window is scrolling.

• 'initial' The window scroll event is ignored and has no effect on menu.
• 'auto' Menu will reposition itself based on the value of position prop when window is scrolling.
• 'close' menu will be closed when window is scrolled.