Forma 36

Menu

Give feedback

Menu is a component that offers a list of choices to the user, such as a set of actions or links. Menu uses Popover component as a base.

Import

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

Examples

You can use following components to build a menu:

  1. <Menu>: The main wrapper that provides nested components with all the context and state.
  2. <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.
  3. <Menu.List>: The wrapper for the menu items. Must be a direct child of <Menu>.
  4. <Menu.Item> The trigger that handles menu selection. Must be a direct child of <Menu.List>.
  5. <Menu.Divider> A visual separator for menu items.
  6. <Menu.SectionTitle> A title that you can use in the menu list.
  7. <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.
  8. <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.
  9. <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>.
  10. <Menu.SubmenuTrigger> The wrapper for the submenu list trigger. Must be a direct child of <Menu.Submenu>.

Basic usage

Open in Playground

With simple Button as a trigger

Open in Playground

With Menu.SectionTitle and Menu.Divider

Open in Playground

Controlled Menu

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.

Open in Playground

Controlled Menu with custom trigger onClick callback

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.

Open in Playground

With Menu list maximum height

Open in Playground

With active and disabled items

Open in Playground

With icons on menu items

Open in Playground

With menu open by default

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


export default function MenuOpenByDefault() {
  return (
    <Menu defaultIsOpen>
      <Menu.Trigger>
        <IconButton
          variant="secondary"
          icon={<MenuIcon />}
          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
import React from 'react';
import {
  MemoryRouter as Router,
  useHref,
  useLinkClickHandler,
} from 'react-router-dom';
import { Menu, IconButton } from '@contentful/f36-components';
import { MenuIcon } 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={<MenuIcon />}
            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>
  );
}

With predefined focused menu item

Open in Playground

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

Open in Playground

Props (API reference)

Open in Storybook

Name

Type

Default

children
required
ReactNode

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.

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

By default, the Menu is uncontrolled (manage it's expanded state by itself) But you can make it controlled by providing boolean (true/false)

offset
[number, number]

The `X-axis` and `Y-axis` offset to position popper element from its trigger element. `[X, Y]`

[1, 4]
onClose
() => void

Callback fired when the Menu closes

onOpen
() => void

Callback fired when the Menu opens

placement
"auto"
"auto-start"
"auto-end"
"top"
"bottom"
"right"
"left"
"top-start"
"top-end"
"bottom-start"
"bottom-end"
"right-start"
"right-end"
"left-start"
"left-end"

Determines the preferred position of the Popover. This position is not guaranteed, as the Popover might be moved to fit the viewport

bottom-start
renderOnlyWhenOpen
false
true

Defines if popover 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 Popover in a React Portal. Rendering content inside a Portal allows the Popover to escape the bounds of its parent while still being positioned correctly. Using a Portal is necessary if an ancestor of the Popover hides overflow.

true

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<any, 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

Name

Type

Default

children
ReactNode

className
string

CSS class to be appended to the root element

css
string
number
false
true
ComponentSelector
Keyframes
SerializedStyles
ArrayInterpolation<undefined>
ObjectInterpolation<undefined>
(theme: any) => Interpolation<undefined>

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.

Help improve this page

Edit on GithubRead the contribution guide