Menu – The wrapper component provides context, state, and focus management, requires a trigger prop.
MenuItem – The trigger that handles menu selection. Must be a direct child of a MenuList.
MenuGroup – A wrapper to group related menu items.
MenuDivider – A visual separator for menu items and groups.
MenuOptionGroup – A wrapper for checkable menu items (radio and checkbox).
MenuItemOption – The checkable menu item, to be used with MenuOptionGroup.

Usage

live

<Menu trigger={<Button iconAfter={iconChevronDown}>Actions</Button>} inPortal>
  <MenuItem>Download</MenuItem>
  <MenuItem>Create a Copy</MenuItem>
  <MenuItem>Mark as Draft</MenuItem>
  <MenuItem>Delete</MenuItem>
  <MenuItem>Attend a Workshop</MenuItem>
</Menu>

Trigger

The trigger prop accepts any system component. If you're passing a custom component that composes a system component, it must accept a ref.

Trigger must accept a ref
A custom component needs to accept a ref so that the menu list can be positioned correctly. You can use forwardRef from @hoverinc/design-system-react-web to supply the ref along with being able to use system props. Without a ref, the menu list will render in an undefined position.

Use menuListProps to pass props to the div that contains MenuItems. This container composes Box so you can pass all Box props to change its style.

Use with caution
Changes to the container should be approved by design and built into the theme styles for this component whenever possible. If there are changes / variants you need, please raise in the #design-system Slack channel first.

live

<Menu
  trigger={<Button>Open</Button>}
  menuListProps={{
    backgroundColor: 'neutral.200',
    onMouseOver: () => console.log('on mouseover'),
    paddingY: '400',
  }}
  inPortal
>
  <MenuItem>Download</MenuItem>
  <MenuItem>Create a Copy</MenuItem>
  <MenuItem>Mark as Draft</MenuItem>
</Menu>

Accessing the internal state

To access the internal state of the Menu, use a function as children or trigger (commonly known as a render prop). You'll get access to the internal state isOpen and method onClose.

live

<Menu
  trigger={({ isOpen }) => (
    <Button iconAfter={isOpen ? iconChevronUp : iconChevronDown}>
      {isOpen ? 'Close' : 'Open'}
    </Button>
  )}
  inPortal
>
  <MenuItem>Download</MenuItem>
  <MenuItem onClick={() => alert('Kagebunshin')}>Create a Copy</MenuItem>
</Menu>

When focus is on the trigger or within the list and you type a letter key, a search begins. Focus will move to the first MenuItem that starts with the letter you typed.

Try it out
Open the menu, try and type any letter, (say, S) to see the focus movement.

live

<Menu trigger={<Button iconAfter={iconChevronDown}>File</Button>} inPortal>
  <MenuItem>New File</MenuItem>
  <MenuItem>New Window</MenuItem>
  <MenuDivider />
  <MenuItem>Open...</MenuItem>
  <MenuItem>Save File</MenuItem>
</Menu>

Example with images

live

<Menu trigger={<Button iconAfter={iconChevronDown}>Your Cats</Button>} inPortal>
  <MenuItem minH="48px">
    <Image
      boxSize="300"
      borderRadius="900"
      src="/images/kitten--100-100.jpg"
      alt="Fluffybuns the destroyer"
      mr="300"
    />
    <span>Fluffybuns the Destroyer</span>
  </MenuItem>
  <MenuItem minH="40px">
    <Image
      boxSize="300"
      borderRadius="full"
      src="/images/kitten--120-120.jpg"
      alt="Simon the pensive"
      mr="300"
    />
    <span>Simon the pensive</span>
  </MenuItem>
</Menu>

Adding icons and commands

You can add icon to each MenuItem by passing the icon prop. To add a commands (or hotkeys) to menu items, you can use the command prop.

live

<Menu trigger={<IconButton icon={iconFilter} label="Options" />} inPortal>
  <MenuItem icon={<Icon icon={iconFolder} />} command="⌘T">
    New Tab
  </MenuItem>
  <MenuItem icon={<Icon icon={iconExternalLink} />} command="⌘N">
    New Window
  </MenuItem>
  <MenuItem icon={<Icon icon={iconArrowForward} />} command="⌘⇧N">
    Open Closed Tab
  </MenuItem>
  <MenuItem icon={<Icon icon={iconFile} />} command="⌘O">
    Open File...
  </MenuItem>
</Menu>

Lazily mounting items

By default, the Menu component renders all children of MenuList to the DOM, meaning that invisible menu items are still rendered but are hidden by styles.

If you want to defer rendering of each children of the menu list until that menu is open, you can use the isLazy prop. This is useful if your Menu needs to be extra performant, or make network calls on mount that should only happen when the component is displayed.

live

<Menu
  isLazy
  trigger={<Button iconAfter={iconChevronDown}>Open Menu</Button>}
  inPortal
>
  {/* MenuItems are not rendered unless Menu is open */}
  <MenuItem>New Window</MenuItem>
  <MenuItem>Open Closed Tab</MenuItem>
  <MenuItem>Open File</MenuItem>
</Menu>

To render menus in a Portal, pass the inPortal prop.

Info
These live code blocks hide overflow, so we're setting inPortal on all the examples

live

<Menu
  inPortal
  isLazy
  trigger={<Button iconAfter={iconChevronDown}>Open Menu</Button>}
>
  <MenuItem>Menu 1</MenuItem>
  <MenuItem>New Window</MenuItem>
  <MenuItem>Open Closed Tab</MenuItem>
  <MenuItem>Open File</MenuItem>
</Menu>

Groups

To group related MenuItems, use the MenuGroup component and pass it a title for the group name.

live

<Menu
  inPortal
  trigger={
    <Button iconBefore={iconUser} iconAfter={iconChevronDown}>
      Profile
    </Button>
  }
>
  <MenuGroup title="Profile">
    <MenuItem>My Account</MenuItem>
    <MenuItem>Payments </MenuItem>
  </MenuGroup>
  <MenuDivider />
  <MenuGroup title="Help">
    <MenuItem>Docs</MenuItem>
    <MenuItem>FAQ</MenuItem>
  </MenuGroup>
</Menu>

Items as links

To render a MenuItem as a link, use the attributes as and href.

live

<Menu inPortal trigger={<Button iconAfter={iconChevronDown}>Open Menu</Button>}>
  <MenuItem as="a" href="#" icon={<Icon icon={iconExternalLink} />}>
    Link 1
  </MenuItem>
  <MenuItem as="a" href="#" icon={<Icon icon={iconExternalLink} />}>
    Link 2
  </MenuItem>
</Menu>

Option groups

You can compose a menu for table headers to help with sorting and filtering options. Use the MenuOptionGroup and MenuItemOption components.

<Menu inPortal trigger={<Button iconBefore={iconFilter}>Filter</Button>}>
  <MenuOptionGroup defaultValue="asc" title="Order" type="radio">
    <MenuItemOption value="asc">Ascending</MenuItemOption>
    <MenuItemOption value="desc">Descending</MenuItemOption>
  </MenuOptionGroup>
  <MenuDivider />
  <MenuOptionGroup title="Country" type="checkbox">
    <MenuItemOption value="email">Email</MenuItemOption>
    <MenuItemOption value="phone">Phone</MenuItemOption>
    <MenuItemOption value="country">Country</MenuItemOption>
  </MenuOptionGroup>
</Menu>

With arrow

Set hasArrow to display an arrow pointing from the menu to the trigger.

live

<Menu
  hasArrow
  trigger={<IconButton label="Actions" icon={iconEllipses} />}
  inPortal
>
  <MenuItem>Download</MenuItem>
  <MenuItem>Create a Copy</MenuItem>
  <MenuItem>Mark as Draft</MenuItem>
  <MenuItem>Delete</MenuItem>
  <MenuItem>Attend a Workshop</MenuItem>
</Menu>

Accessibility

Keyboard Interaction

Key	Action
`Enter` or `Space`	When `MenuButton` receives focus, opens the menu and places focus on the first menu item.
`ArrowDown`	When `MenuButton` receives focus, opens the menu and moves focus to the first menu item.
`ArrowUp`	When `MenuButton` receives focus, opens the menu and moves focus to the last menu item.
`Escape`	When the menu is open, closes the menu and sets focus to the `MenuButton`.
`Tab`	no effect
`Home`	When the menu is open, moves focus to the first item.
`End`	When the menu is open, moves focus to the last item.
`A-Z` or `a-z`	When the menu is open, moves focus to the next menu item with a label that starts with the typed character if such an menu item exists.

ARIA roles

For MenuButton:

role is set to button.
aria-haspopup is set to menu.
When the menu is displayed, aria-expanded is set to true.
aria-controls is set to the id of the MenuList.

For MenuList:

role is set to menu.
aria-orientation is set to vertical.

For MenuItem:

role is set to menuitem.
Gets one of these roles menuitem/menuitemradio/ menuitemcheckbox.

React Native

Menu is built with Tamagui and provides a dropdown interface with trigger, dropdown, items, and dividers for iOS and Android platforms.

Usage

import { iconChevronDown, iconTrash } from '@hoverinc/icons/native';
import React, { useState } from 'react';
import {
  Heading,
  Icon,
  Menu,
  XStack,
} from '@hoverinc/design-system-react-native';
const App = () => {
  const [open, setOpen] = useState(false);
  return (
    <Menu
      onOpenChange={() => setOpen(!open)}
      open={open}
      placement="bottom-end"
    >
      <Menu.Trigger>
        <XStack alignItems="center" gap="$100" pressStyle={{ opacity: 0.5 }}>
          <Heading size="xs">Homeowner</Heading>
          <Icon icon={iconChevronDown} size="tiny" />
        </XStack>
      </Menu.Trigger>
      <Menu.Dropdown>
        <Menu.Item isDisabled>Invited to scan</Menu.Item>
        <Menu.Divider />
        <Menu.Item isSelected>Selected Item</Menu.Item>
        <Menu.Item onPress={() => setOpen(false)}>Send reminder</Menu.Item>
        <Menu.Item onPress={() => setOpen(false)}>Copy link</Menu.Item>
        <Menu.Item
          color="$dangerSecondary"
          iconAfter={iconTrash}
          onPress={() => setOpen(false)}
        >
          Sign Out
        </Menu.Item>
      </Menu.Dropdown>
    </Menu>
  );
};

Components

The Menu component exports the following sub-components:

Menu – The main wrapper component that provides context and state management
Menu.Trigger – The trigger element that opens the menu
Menu.Dropdown – The container for menu items
Menu.Item – Individual menu items with support for selection, disabled state, icons, and custom colors
Menu.Divider – Visual separator between menu items

Menu items support several states and configurations:

// Basic menu item
<Menu.Item>Basic Item</Menu.Item>
// Selected state
<Menu.Item isSelected>Selected Item</Menu.Item>
// Disabled state
<Menu.Item isDisabled>Disabled Item</Menu.Item>
// With icon after
<Menu.Item iconAfter={iconChevronRight}>Item with Icon</Menu.Item>
// With custom color
<Menu.Item color="$dangerSecondary">Danger Item</Menu.Item>

Placement

The menu can be positioned relative to its trigger using the placement prop:

<Menu placement="bottom-start">...</Menu>
<Menu placement="top-end">...</Menu>
<Menu placement="left">...</Menu>
<Menu placement="right">...</Menu>

Controlled vs Uncontrolled

The Menu component supports both controlled and uncontrolled usage:

// Controlled
const [open, setOpen] = useState(false);
<Menu open={open} onOpenChange={setOpen}>...</Menu>
// Uncontrolled
<Menu defaultOpen={false}>...</Menu>

Design System

Settings

Menu

React

Usage

Trigger

Trigger must accept a ref

Menu container styles

Use with caution

Accessing the internal state

Letter navigation

Try it out

Example with images

Adding icons and commands

Lazily mounting items

Rendering the Menu in a Portal

Info

Groups

Items as links

Option groups

With arrow

Accessibility

Keyboard Interaction

ARIA roles

React Native

Usage

Components

Menu Item States

Placement

Controlled vs Uncontrolled