Components

#
#

Menu is a top-level component that contains menu items and other lower level submenus.

Working with a MenuButton or a compatible button component, Menu manages states which controls the display of its contents and maintains focus among its descendants.

It should be able to serve the majority of use cases. If you need more controls on how and when a menu is open or closed, you might use a ControlledMenu.

Props

NameTypeDefaultDescription
alignstring'start'

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

It sets alignment of menu with anchor element.

aria-labelstring

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'.

arrowboolean

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

arrowClassNamestring | function

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'.
arrowStylesobject | function

A style object that will be applied to the inline style of menu arrow DOM element.

Styles targeting specific component state should be supplied as nested objects under each state key.

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

When a function is provided, it will be called by passing an object with the above properties and should return a flattened style object.

boundingBoxPaddingstring

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

boundingBoxRefobject

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.

containerPropsobject

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

directionstring'bottom' or 'right' for SubMenu

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

It sets direction in which menu expands against anchor element.

initialMountedboolean

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.

instanceRefReact.Ref <MenuInstance>

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
menuButtonelement | function

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.

menuClassNamestring | function

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'.
menuStylesobject | function

A style object that will be applied to the inline style of menu DOM element.

Styles targeting specific component state should be supplied as nested objects under each state key.

  • 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'.

When a function is provided, it will be called by passing an object with the above properties and should return a flattened style object.

offsetXnumber0

Set the horizontal distance (in pixels) between menu and its anchor element. The value can be negative.

offsetYnumber0

Set the vertical distance (in pixels) between menu and its anchor element. The value can be negative.

onItemClickfunction

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)
onMenuChangefunction

Event fired when menu states have changed.

Event object properties:

  • open: bool indicates if the menu is open.
overflowstring'visible'

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.

portalboolean

If true, menu is rendered as a direct child of document.body.

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.

positionstring'auto'

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.
repositionstring'auto'

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.
repositionFlagnumber | string

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.

submenuCloseDelaynumber150

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.

submenuOpenDelaynumber300

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

themingstring

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

transition
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 delay to close.

transitionTimeoutnumber500

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

unmountOnCloseboolean

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

viewScrollstring'initial'

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.

    Note: for the best user experience, if the overflow prop is set to a value other than 'visible', viewScroll will behave as 'close'.

  • 'close' menu will be closed when window is scrolled.
#

MenuItem represents an item under a menu which can be activated.

It can be a regular menu item, a checkbox item (type="checkbox"), or a radio item (direct child of MenuRadioGroup).

Props

NameTypeDefaultDescription
checkedboolean

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

childrennode | function

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.
  • active: bool indicates if the menu item is active (pressed).
  • 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.
classNamestring | function

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.
  • active: bool indicates if the menu item is active (pressed).
  • 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.
disabledboolean

Set true to disabled the menu item.

hrefstringIf provided, menu item renders an HTML <a> element with this href attribute.
onClickfunction

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)
stylesobject | function

A style object that will be applied to the inline style of menu item DOM element.

Styles targeting specific component state should be supplied as nested objects under each state key.

  • hover: bool indicates if the menu item is being hovered and has focus.
  • active: bool indicates if the menu item is active (pressed).
  • 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.

When a function is provided, it will be called by passing an object with the above properties and should return a flattened style object.

typestring

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

Please note menu items under a MenuRadioGroup will have type set to 'radio' automatically.

valueany

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.

#

MenuButton works with a Menu and controls its open and close.

Props

NameTypeDefaultDescription
childrennodeContents of the menu button.
classNamestring | function

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.
disabledboolean

Set true to disabled the menu button.

stylesobject | function

A style object that will be applied to the inline style of menu button DOM element.

Styles targeting specific component state should be supplied as nested objects under each state key.

  • open: bool indicates if the menu is open.

When a function is provided, it will be called by passing an object with the above properties and should return a flattened style object.

FocusableItem

#

FocusableItem can be used to wrap focusable element (input, button) in a menu item. It manages focus automatically among other menu items during mouse and keyboard interactions.

Props

NameTypeDefaultDescription
childrenfunction

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.
classNamestring | function

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.
disabledboolean

Set true to disabled 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.

stylesobject | function

A style object that will be applied to the inline style of focusable item DOM element.

Styles targeting specific component state should be supplied as nested objects under each state key.

  • 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.

When a function is provided, it will be called by passing an object with the above properties and should return a flattened style object.

#

SubMenu is a menu container under other menu or submenu components.

It consists of a menu item and a sub-level menu containing submenu items. Use label prop to set its own contents, and place the submenu items it contains in the children prop.

Props

NameTypeDefaultDescription
alignstring'start'

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

It sets alignment of menu with anchor element.

aria-labelstring

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'.

arrowboolean

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

arrowClassNamestring | function

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'.
arrowStylesobject | function

A style object that will be applied to the inline style of menu arrow DOM element.

Styles targeting specific component state should be supplied as nested objects under each state key.

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

When a function is provided, it will be called by passing an object with the above properties and should return a flattened style object.

directionstring'bottom' or 'right' for SubMenu

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

It sets direction in which menu expands against anchor element.

disabledboolean

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

instanceRefReact.Ref <MenuInstance>

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
itemPropsobject

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

itemProps.classNamestring | function

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.
  • active: bool indicates if the submenu item is active (pressed).
  • disabled: bool indicates if the submenu and item are disabled.
itemProps.stylesobject | function

A style object that will be applied to the inline style of submenu item DOM element.

Styles targeting specific component state should be supplied as nested objects under each state key.

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

When a function is provided, it will be called by passing an object with the above properties and should return a flattened style object.

labelnode | function

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.
  • active: bool indicates if the submenu item is active (pressed).
  • disabled: bool indicates if the submenu and item are disabled.
menuClassNamestring | function

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'.
menuStylesobject | function

A style object that will be applied to the inline style of menu DOM element.

Styles targeting specific component state should be supplied as nested objects under each state key.

  • 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'.

When a function is provided, it will be called by passing an object with the above properties and should return a flattened style object.

offsetXnumber0

Set the horizontal distance (in pixels) between menu and its anchor element. The value can be negative.

offsetYnumber0

Set the vertical distance (in pixels) between menu and its anchor element. The value can be negative.

onMenuChangefunction

Event fired when menu states have changed.

Event object properties:

  • open: bool indicates if the menu is open.
openTriggerundefined | 'none' | 'clickOnly'
  • 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.
overflowstring'visible'

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.

positionstring'auto'

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.

MenuRadioGroup

#

MenuRadioGroup is a container of menu items which are similar to radio buttons.

All menu items under a MenuRadioGroup are in the same radio group and have type="radio". It's unnecessary to manually set the property.

Props

NameTypeDefaultDescription
aria-labelstring

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'.

childrennode

The only permitted children is MenuItem.

classNamestring

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

namestring

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.

onRadioChangefunction

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)
stylesobject

A style object that will be applied to the inline style of radio group DOM element.

valueany

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.

#

MenuGroup is used to wrap a subset of related menu items and make them scrollable.

Props

NameTypeDefaultDescription
classNamestring

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

stylesobject

A style object that will be applied to the inline style of menu group DOM element.

takeOverflowboolean

Set true to apply overflow of the parent menu to the group. Only one MenuGroup in a menu is allowed to have this prop.

#

MenuHeader can be used to provide presentational information for a group of related menu items.

Props

NameTypeDefaultDescription
classNamestring

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

stylesobject

A style object that will be applied to the inline style of menu header DOM element.

#

MenuDivider can be used to make a group of related menu items visually separated from other items. It has aria roles that can be recognised by assistive technologies.

Props

NameTypeDefaultDescription
classNamestring

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

stylesobject

A style object that will be applied to the inline style of menu divider DOM element.

ControlledMenu

#

ControlledMenu is a top-level component that contains menu items and other lower level submenus.

It's different from a Menu that ControlledMenu allows you to control how and when a menu is open or closed, rather than controlled by a menu button.

For example, you might need to open a menu when something on the page is hovered by a mouse, or you need to position the menu to something other than the menu button. ControlledMenu can be also use to implement a context menu.

When using ControlledMenu, it's your job to set focus to the desirable item after menu opens and move focus back to your menu button after it closes, which can be done by setting menuItemFocus, and in the onClose event, respectively. However, depending on your requirements, both of them might be optional.

Props

NameTypeDefaultDescription
alignstring'start'

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

It sets alignment of menu with anchor element.

anchorPointobject

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 }.

anchorRefobject

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.

aria-labelstring

Sets aria-label attribute on the menu DOM element.

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

arrowboolean

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

arrowClassNamestring | function

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'.
arrowStylesobject | function

A style object that will be applied to the inline style of menu arrow DOM element.

Styles targeting specific component state should be supplied as nested objects under each state key.

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

When a function is provided, it will be called by passing an object with the above properties and should return a flattened style object.

boundingBoxPaddingstring

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

boundingBoxRefobject

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.

captureFocusbooleantrue

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

containerPropsobject

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

directionstring'bottom' or 'right' for SubMenu

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

It sets direction in which menu expands against anchor element.

initialMountedboolean

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.

menuClassNamestring | function

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'.
menuItemFocusobject

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.

menuStylesobject | function

A style object that will be applied to the inline style of menu DOM element.

Styles targeting specific component state should be supplied as nested objects under each state key.

  • 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'.

When a function is provided, it will be called by passing an object with the above properties and should return a flattened style object.

offsetXnumber0

Set the horizontal distance (in pixels) between menu and its anchor element. The value can be negative.

offsetYnumber0

Set the vertical distance (in pixels) between menu and its anchor element. The value can be negative.

onClosefunction

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'.
onItemClickfunction

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)
overflowstring'visible'

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.

portalboolean

If true, menu is rendered as a direct child of document.body.

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.

positionstring'auto'

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.
repositionstring'auto'

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.
repositionFlagnumber | string

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.

statestring

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

submenuCloseDelaynumber150

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.

submenuOpenDelaynumber300

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

themingstring

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

transition
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 delay to close.

transitionTimeoutnumber500

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

unmountOnCloseboolean

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

viewScrollstring'initial'

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.

    Note: for the best user experience, if the overflow prop is set to a value other than 'visible', viewScroll will behave as 'close'.

  • 'close' menu will be closed when window is scrolled.

Hooks

#

useMenuState

#

useMenuState is a custom Hook that helps manage the states of ControlledMenu.

The Hook returns several states which are used by ControlledMenu and can be spread to its props. See an example.

function useMenuState(options?: {
    initialMounted?: boolean;
    unmountOnClose?: boolean;
    transition?: boolean | {
        open?: boolean;
        close?: boolean;
        item?: boolean;
    };
    transitionTimeout?: number;
}): {
    state?: 'opening' | 'open' | 'closing' | 'closed';
    toggleMenu: (open?: boolean) => void;
    endTransition: () => void;
};

The hook function options are the same as props on Menu component.

toggleMenu:

  • If no parameter is supplied, this function will toggle state between open and close phases.
  • You can set a boolean parameter to explicitly switch into one of the two phases.

The Menu component uses this hook internally to manage its states.

Utilities

#

applyHOC

#

A helper function which copies statics if you create HOC on React-Menu components. It accepts an HOC and returns a new HOC with the same signature. See a CodeSandbox example for its usage.

Note: some third-party HOC utilities (such as the connect of react-redux) have already copied statics so you don't need to call this helper.

applyStatics

#

It's similar to applyHOC, but accepts a source component with statics to be copied and returns an HOC which accepts a wrapped component.

It creates a composable HOC that can be placed at the leftmost of a compose utility.

It also can be used to create new components which wrap and return one of react-menu's components. See a CodeSandbox example

Accessibility

#

React-Menu implements WAI-ARIA roles, states, and properties which adhere to the WAI-ARIA Authoring Practices. For more details, please refer to the website.

Keyboard

#

React-Menu supports the following keyboard interactions:

Menu

  • Return activates a menu item and closes the menu.
  • Space activates a menu item and closes the menu; for radio and checkbox item, activates the menu item without closing the menu.
  • Down Arrow moves focus to the next item, wrapping from the last to the first.
  • Up Arrow moves focus to the previous item, wrapping from the first to the last.
  • Home moves focus to the first item.
  • End moves focus to the last item.
  • Esc Closes a menu and move focus to its associated menu button.
  • Left Arrow Closes a submenu if it is open.
  • Return | Space | Right Arrow When focus is in a submenu item, opens the submenu, and moves focus to the first menu item.

MenuButton

  • Return | Space | Down Arrow opens the associated menu and moves focus to the first menu item.
  • Up Arrow opens the associated menu and moves focus to the last menu item.