Technical information

Menu is based on the popover component and offers compound components to build flexible menus that can be nested.

Compound components

<Menu.Trigger> The wrapper for the menu list trigger. Must be a direct child of <Menu>.
NOTE: 🚨 Ensure that the component that you pass accepts ref. Consider using forwardRef for functional components.
<Menu.List>: The wrapper for the menu items. Must be a direct child of <Menu>.
<Menu.Item> The trigger that handles menu selection. Must be a direct child of <Menu.List>.
<Menu.Divider> A visual separator for menu items.
<Menu.SectionTitle> A title that you can use in the menu list.
<Menu.ListHeader> The wrapper for one menu item that will be sticked to the top of the menu list. <Menu.Item> must be provided as a child.
<Menu.ListFooter> The wrapper for one menu item that will be sticked to the bottom of the menu list. <Menu.Item> must be provided as a child.
deprecated <Menu.Submenu> The wrapper for for submenu components. Structure of the children remains the same like in <Menu>, except you should use <Menu.SubmenuTrigger> instead of <Menu.Trigger>.
<Menu.SubmenuTrigger> The wrapper for the submenu list trigger. Must be a direct child of <Menu.Submenu>.

Import

import { Menu } from '@contentful/f36-components';

Examples

Basic usage

function BasicMenu() {
  return (
    <Menu>
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<ListIcon />}
          aria-label="toggle menu"
        />
      </Menu.Trigger>
      <Menu.List>
        <Menu.Item>Create an entry</Menu.Item>
        <Menu.Item>Remove an entry</Menu.Item>
        <Menu.Item>Embed existing entry</Menu.Item>
      </Menu.List>
    </Menu>
  );
}

Open in Playground

With simple Button as a trigger

function MenuWithButtonAsTrigger() {
  return (
    <Menu>
      <Menu.Trigger>
        <Button>toggle menu</Button>
      </Menu.Trigger>
      <Menu.List>
        <Menu.Item>Create an entry</Menu.Item>
        <Menu.Item>Remove an entry</Menu.Item>
        <Menu.Item>Embed existing entry</Menu.Item>
      </Menu.List>
    </Menu>
  );
}

Open in Playground

With Menu.SectionTitle and Menu.Divider

function MenuWithTitle() {
  return (
    <Menu>
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<ListIcon />}
          aria-label="toggle menu"
        />
      </Menu.Trigger>
      <Menu.List>
        <Menu.SectionTitle>Entry</Menu.SectionTitle>
        <Menu.Item>Create an entry</Menu.Item>
        <Menu.Item>Remove an entry</Menu.Item>
        <Menu.Item>Embed existing entry</Menu.Item>
        <Menu.Divider />
        <Menu.Item as="a" href="https://contentful.com" target="_blank">
          About Contentful
        </Menu.Item>
      </Menu.List>
    </Menu>
  );
}

Open in Playground

By default the Menu component is uncontrolled. So when user clicks on the trigger, the menu opens/closes. But you can control it by passing isOpen prop and onClose, onOpen callbacks.

function ControlledMenu() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <Menu
      isOpen={isOpen}
      onOpen={() => setIsOpen(true)}
      onClose={() => setIsOpen(false)}
    >
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<ListIcon />}
          aria-label="toggle menu"
        />
      </Menu.Trigger>
      <Menu.List>
        <Menu.Item>Create an entry</Menu.Item>
        <Menu.Item>Remove an entry</Menu.Item>
        <Menu.Item>Embed existing entry</Menu.Item>
      </Menu.List>
    </Menu>
  );
}

Open in Playground

In most cases, you will use the controlled approach. But if you have to provide your own toggle menu logic on the trigger component, you can do this by providing onClick callback on trigger component and omitting onOpen callback on the Menu component.

function ControlledMenuWithCustomTriggerLogic() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <Menu isOpen={isOpen} onClose={() => setIsOpen(false)}>
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<ListIcon />}
          aria-label="toggle menu"
          onClick={() => setIsOpen(!isOpen)}
        />
      </Menu.Trigger>
      <Menu.List>
        <Menu.Item>Create an entry</Menu.Item>
        <Menu.Item>Remove an entry</Menu.Item>
        <Menu.Item>Embed existing entry</Menu.Item>
      </Menu.List>
    </Menu>
  );
}

Open in Playground

function MenuWithMaxHeight() {
  return (
    <Menu>
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<ListIcon />}
          aria-label="toggle menu"
        />
      </Menu.Trigger>
      <Menu.List style={{ maxHeight: '200px' }}>
        <Menu.Item>Item 1</Menu.Item>
        <Menu.Item>Item 2</Menu.Item>
        <Menu.Item>Item 3</Menu.Item>
        <Menu.Item>Item 4</Menu.Item>
        <Menu.Item>Item 5</Menu.Item>
        <Menu.Item>Item 6</Menu.Item>
        <Menu.Item>Item 7</Menu.Item>
        <Menu.Item>Item 8</Menu.Item>
        <Menu.Item>Item 9</Menu.Item>
        <Menu.Item>Item 10</Menu.Item>
        <Menu.Item>Item 11</Menu.Item>
        <Menu.Item>Item 12</Menu.Item>
      </Menu.List>
    </Menu>
  );
}

Open in Playground

With active and disabled items

function MenuWithDisabledItems() {
  return (
    <Menu>
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<ListIcon />}
          aria-label="toggle menu"
        />
      </Menu.Trigger>
      <Menu.List>
        <Menu.Item>Item 1</Menu.Item>
        <Menu.Item isActive>Item 2</Menu.Item>
        <Menu.Item>Item 3</Menu.Item>
        <Menu.Item isDisabled>Item 4 (disabled)</Menu.Item>
        <Menu.Item>Item 5</Menu.Item>
        <Menu.Item>Item 6</Menu.Item>
        <Menu.Item isDisabled>Item 7 (disabled)</Menu.Item>
        <Menu.Item>Item 8</Menu.Item>
      </Menu.List>
    </Menu>
  );
}

Open in Playground

function MenuWithIcons() {
  return (
    <Menu>
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<ListIcon />}
          aria-label="toggle menu"
        />
      </Menu.Trigger>
      <Menu.List>
        <Menu.Item icon={<CheckIcon />}>Item 1</Menu.Item>
        <Menu.Item>Item 2</Menu.Item>
        <Menu.Item icon={<CheckIcon />}>Item 3</Menu.Item>
      </Menu.List>
    </Menu>
  );
}

Open in Playground

import React from 'react';
import { Menu, IconButton } from '@contentful/f36-components';
import { ListIcon } from '@contentful/f36-icons';

export default function MenuOpenByDefault() {
  return (
    <Menu defaultIsOpen>
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<ListIcon />}
          aria-label="toggle menu"
        />
      </Menu.Trigger>
      <Menu.List>
        <Menu.Item>Create an entry</Menu.Item>
        <Menu.Item>Remove an entry</Menu.Item>
        <Menu.Item>Embed existing entry</Menu.Item>
      </Menu.List>
    </Menu>
  );
}

function MenuWithStickyHeaderFooter() {
  return (
    <Menu>
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<ListIcon />}
          aria-label="toggle menu"
        />
      </Menu.Trigger>
      <Menu.List style={{ maxHeight: '300px' }}>
        <Menu.ListHeader>
          <Menu.Item>Item header</Menu.Item>
        </Menu.ListHeader>
        <Menu.Item>Item 1</Menu.Item>
        <Menu.Item>Item 2</Menu.Item>
        <Menu.Item>Item 3</Menu.Item>
        <Menu.Item>Item 4</Menu.Item>
        <Menu.Item>Item 5</Menu.Item>
        <Menu.Item>Item 6</Menu.Item>
        <Menu.Item>Item 7</Menu.Item>
        <Menu.Item>Item 8</Menu.Item>
        <Menu.Item>Item 9</Menu.Item>
        <Menu.Item>Item 10</Menu.Item>
        <Menu.ListFooter>
          <Menu.Item>Item footer</Menu.Item>
        </Menu.ListFooter>
      </Menu.List>
    </Menu>
  );
}

Open in Playground

With React Router links

import React from 'react';
import {
  MemoryRouter as Router,
  useHref,
  useLinkClickHandler,
} from 'react-router-dom';
import { Menu, IconButton } from '@contentful/f36-components';
import { ListIcon } from '@contentful/f36-icons';

function MenuLink({ children, replace = false, to, ...props }) {
  const href = useHref(to);
  const handleClick = useLinkClickHandler(to, {
    replace,
  });

  return (
    <Menu.Item {...props} as="a" href={href} onClick={handleClick}>
      {children}
    </Menu.Item>
  );
}

export default function MenuWithReactRouterLinks() {
  return (
    <Router>
      <Menu>
        <Menu.Trigger>
          <IconButton
            variant="secondary"
            icon={<ListIcon />}
            aria-label="toggle menu"
          />
        </Menu.Trigger>
        <Menu.List>
          <MenuLink to="/">Home</MenuLink>
          <MenuLink to="/about">About</MenuLink>
          <MenuLink to="/other">Other</MenuLink>
        </Menu.List>
      </Menu>
    </Router>
  );
}

function MenuWithPredefinedFocusedMenuItem() {
  return (
    <Menu>
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<ListIcon />}
          aria-label="toggle menu"
        />
      </Menu.Trigger>
      <Menu.List>
        <Menu.Item>Create an entry</Menu.Item>
        <Menu.Item isInitiallyFocused>Remove an entry</Menu.Item>
        <Menu.Item>Embed existing entry</Menu.Item>
      </Menu.List>
    </Menu>
  );
}

Open in Playground

With nested submenu

By default props like closeOnSelect, closeOnBlur, closeOnEsc that you pass to Menu will be shared to all submenus but you can redefine them on any submenu by passing those props directly to that Submenu.

function MenuWithSubmenu() {
  return (
    <Menu>
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<ListIcon />}
          aria-label="toggle menu"
        />
      </Menu.Trigger>
      <Menu.List>
        <Menu.Item>Create an entry</Menu.Item>
        <Menu>
          <Menu.SubmenuTrigger>Remove an entry</Menu.SubmenuTrigger>
          <Menu.List>
            <Menu.Item>Sub item 1</Menu.Item>
            <Menu.Item>Sub item 2</Menu.Item>
            <Menu.Item>Sub item 3</Menu.Item>
          </Menu.List>
        </Menu>
        <Menu.Item>Embed existing entry</Menu.Item>
      </Menu.List>
    </Menu>
  );
}

Open in Playground

Props (API reference)

Open in Storybook

Name	Type	Default
autoFocus	false true If true, the Menu will be focused after opening	true
children	ReactNode Menu compound children (Trigger, List, Item, etc.)
closeOnBlur	false true If true, the menu will close when you blur out it by clicking outside Note: This prop will be propagated to all submenus, unless you will override it with props on submenu itself	true
closeOnEsc	false true If true, the menu will close when you hit the Esc key Note: This prop will be propagated to all submenus, unless you will override it with props on submenu itself	true
closeOnSelect	false true If `true`, the Menu will close when a menu item is clicked Note: This prop will be propagated to all submenus, unless you will override it with props on submenu itself	true
defaultIsOpen	false true If `true`, the Menu will be initially opened. This property has no influence on the uncontrolled status of the Menu
isAutoalignmentEnabled	false true Boolean to control if popover is allowed to change its placement automatically based on available space in the viewport. For example: If you set placement prop to bottom, but there isn't enough space to position the popover in that direction, it will change the popper placement to top. As soon as enough space is detected, the placement will be reverted to the defined one. If you want the popover to strictly follow the placement prop you should set this prop to false.	true
isFullWidth	false true Boolean to determine if the Popover should be the same width as the trigger element	false
isOpen	false true
offset	number { mainAxis?: number; crossAxis?: number; alignmentAxis?: number; } Derivable<OffsetValue> Single number as short hand for `mainAxis` Or object which can contain `mainAxis`, `crossAxis` or `alignmentAxis`	0
onClose	() => void (() => void) & (() => void) (() => void) & (() => void) & (() => void) (() => void) & (() => void) & (() => void) Callback fired when the Menu closes
onOpen	() => void (() => void) & (() => void) (() => void) & (() => void) & (() => void) (() => void) & (() => void) & (() => void) Callback fired when the Menu opens
placement	"top" "right" "bottom" "left" "top-start" "top-end" "right-start" "right-end" "bottom-start" "bottom-end" "left-start" "left-end" "auto" Determines the preferred position of where the MenuList opens. This position is not guaranteed, as the MenuList might be moved to fit the viewport.	bottom-start OR right-start
renderOnlyWhenOpen	false true Defines if the menu list content should be rendered in the DOM only when it's open or all the time (after the component has been mounted)	true
usePortal	false true Boolean to control whether or not to render the Menu in a React Portal. Rendering content inside a Portal allows the Menu to escape the bounds of its parent while still being positioned correctly. Using a Portal is necessary if an ancestor of the Menu hides overflow.	true
useTypeahead	false true Boolean to control wether or not to enable Typeahead functionality which enables focus an item as the user types

Menu.Item

Name	Type	Default
as	HTML Tag or React Component (e.g. div, span, etc)
children	ReactNode
className	string CSS class to be appended to the root element
icon	ReactElement<unknown, string \| JSXElementConstructor<any>> Expects any of the icon components. Renders the icon aligned to the start
isActive	false true Marks item as active
isDisabled	false true Marks item as disabled
isInitiallyFocused	false true Sets focus on item
testId	string A [data-test-id] attribute used for testing purposes

Menu.List

Name	Type	Default
children	ReactNode
className	string CSS class to be appended to the root element
testId	string A [data-test-id] attribute used for testing purposes

Content guidelines

Use an interactive element such as button for Menu.Trigger

Accessibility

When the menu is opened, focus is moved to the first menu item. Or to the one that has isInitiallyFocused prop set to true.
When the menu is closed, focus returned back to the trigger element.
You can use arrow keys (ArrowUp and ArrowDown) to navigate through menu items.
When the menu is open, click on Esc key will close the popover. If you set closeOnEsc to false, it will not close.
When the menu is open, click outside menu or blurring out will close the menu. If you set closeOnBlur to false, it will not close.
All the necessary a11y attributes for Menu.List, Menu.Trigger and Menu.Item are provided.

Menu

Technical information

Compound components

Import

Examples

Basic usage

With simple Button as a trigger

With Menu.SectionTitle and Menu.Divider

Controlled Menu

Controlled Menu with custom trigger onClick callback

With Menu list maximum height

With active and disabled items

With icons on menu items

With menu open by default

With sticky header and footer

With React Router links

With predefined focused menu item

With nested submenu

Props (API reference)

Menu

Name

Type

Default

Menu.Item

Name

Type

Default

Menu.List

Name

Type

Default

Content guidelines

Accessibility

Help improve this page