@szhsin/react-menu

React-Menu is an accessible, unstyled React menu library with the following capabilities:

• Menu Types: Supports dropdown, hover, and context menus.
• Menu Items: Includes support for radio and checkbox menu items.
• Nesting: Allows for unlimited submenu nesting.
• Accessibility: Implements the WAI-ARIA menu pattern and provides full keyboard interaction support.
• Compatibility: Compatible with React 18+ concurrent rendering and supports server-side rendering (SSR).
• Styling: Lightweight and unstyled, allowing for complete custom styling.

By default, a Menu and its items are not mounted into the DOM until the menu is opened for the first time. To ensure that a menu and all its descendants are rendered into the HTML string during server-side rendering (SSR), set the initialMounted prop to true.

If you are using ControlledMenu with the useMenuState hook, pass initialMounted: true within the configuration object.

<Menu initialMounted />

To apply additional HTML attributes (like className or style) or event handlers (like onClick) to the element rendering the submenu label, use the itemProps prop on the SubMenu component.

<SubMenu
  itemProps={{
    className: 'submenu-label',
    style: { backgroundColor: 'lightblue' },
    onClick: () => console.log('Clicked!')
  }}
/>

You can install the React-Menu library using npm or Yarn.

npm install @szhsin/react-menu

or

yarn add @szhsin/react-menu

In v4, the offsetX and offsetY props have been replaced by gap and shift. These new props automatically account for the menu's placement direction, eliminating the need to manually calculate offsets based on whether the menu is appearing on the top, bottom, left, or right of the anchor.

To create a 10-pixel gap between a menu and its anchor, use the gap prop instead of conditional offsetX/offsetY logic.

<Menu gap={10} />

In v4, the individual arrowClassName and arrowStyle props have been consolidated into a single arrowProps object. This new prop allows you to pass any attributes or event handlers directly onto the menu's arrow element.

Instead of passing class names and styles as top-level props, wrap them in an object passed to arrowProps.

<Menu
  arrowProps={{
    className: 'my-custom-arrow',
    style: { backgroundColor: 'blue' }
  }}
/>

The label prop of the SubMenu component is not limited to plain strings; it accepts any valid JSX element. This allows you to compose complex labels containing images, icons, or other React components.

<SubMenu
  label={
    <>
      <img src="edit.png" alt="edit" />
      Edit
      <ArrowIcon />
    </>
  }
/>

To create a menu, import the core components: Menu, MenuItem, MenuButton, and SubMenu. The Menu component requires a menuButton prop which accepts a component (like MenuButton) to trigger the menu. You can nest SubMenu components within a Menu to create unlimited levels of submenus.

import { Menu, MenuItem, MenuButton, SubMenu } from '@szhsin/react-menu';

export default function App() {
  return (
    <Menu menuButton={<MenuButton>Open menu</MenuButton>}>
      <MenuItem>New File</MenuItem>
      <MenuItem>Save</MenuItem>
      <SubMenu label="Edit">
        <MenuItem>Cut</MenuItem>
        <MenuItem>Copy</MenuItem>
        <MenuItem>Paste</MenuItem>
      </SubMenu>
      <MenuItem>Print...</MenuItem>
    </Menu>
  );
}

React-Menu provides hooks for managing interaction and state. The following hooks are exported from the main entry point:

• useClick: For handling click interactions.
• useHover: For handling hover interactions.
• useMenuState: For managing the internal state of a menu.

You can control a Menu instance programmatically by passing a ref to the instanceRef prop. This exposes methods to open and close the menu from your own logic.

Exposed Methods

• openMenu(position): Opens the menu.
• closeMenu(): Closes the menu.

const menuRef = useRef<{ openMenu: () => void; closeMenu: () => void }>(null);

// ...

<Menu 
  instanceRef={menuRef} 
  menuButton={<button>Open Menu</button>} 
/>

// Later in your code:
// menuRef.current?.openMenu();
// menuRef.current?.closeMenu();

useImperativeHandle(instanceRef, () => ({
    openMenu,
    closeMenu: () => toggleMenu(false)
}));