The responsive layout is in early preview. Please report any bugs.

Alpha components are ready for you to use in production. Components such as Menu are likely to not see any API changes. This is only an alpha due to the lack of documentation and minimal design. Feel free to share your experience using this component at #help-design-system or start a discussion on GitHub.

Guidelines#

A menu presents a list of menu items that a user can choose to perform an action with. This component includes a menu trigger (a button in our case) and a menu comprising of menu items that are shown upon actioning the trigger. A menu item can be used to perform an action, a page navigation or show a sub menu.

Each menu item can only perform a single action.

Do not nest multiple actions within a menu item

Please do not add additional actionable elements inside a menu item. They will not be keyboard accessible.

Examples#

const MenuExample = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="primary">
        Actions you can take <ChevronDownIcon decorative />
      </MenuButton>
      <Menu {...menu} aria-label="Actions">
        <MenuItem {...menu}>Call your representatives</MenuItem>
        <MenuItem {...menu}>Support black-owned businesses</MenuItem>
        <MenuItem {...menu}>Vote in national, state, and local elections</MenuItem>
      </Menu>
    </>
  );
};

render(
  <MenuExample />
)

const MenuExample = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="primary">
        Actions you can take <ChevronDownIcon decorative />
      </MenuButton>
      <Menu {...menu} aria-label="Actions">
        <MenuItem {...menu}>Call your representatives</MenuItem>
        <MenuItem {...menu}>Support black-owned businesses</MenuItem>
        <MenuItem {...menu}>Vote in national, state, and local elections</MenuItem>
      </Menu>
    </>
  );
};
render(
  <MenuExample />
)

Use MenuGroups to create hierarchy or logical groupings within longer menus. MenuGroups have a visible group label that should describe the grouping clearly. They can be given a prefix icon; please only use icons in a decorative manner and make the label descriptive standalone.

Add separators between MenuGroups and other menu items.

const MenuGroupExample = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="primary">
        Cool places <ChevronDownIcon decorative />
      </MenuButton>
      <Menu {...menu} aria-label="Actions">
        <MenuGroup label="Social media" icon={<AttachIcon decorative />}>
          <MenuItem {...menu}>Twitter</MenuItem>  
          <MenuItem {...menu}>Myspace</MenuItem>  
          <MenuItem {...menu}>Dribbble</MenuItem>  
        </MenuGroup>
        <MenuSeparator />
        <MenuGroup label="Search engines">
          <MenuItem {...menu}>Ecosia</MenuItem>  
          <MenuItem {...menu}>DuckDuckGo</MenuItem>  
        </MenuGroup>
      </Menu>
    </>
  );
};

render(
  <MenuGroupExample />
)

const MenuGroupExample = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="primary">
        Cool places <ChevronDownIcon decorative />
      </MenuButton>
      <Menu {...menu} aria-label="Actions">
        <MenuGroup label="Social media" icon={<AttachIcon decorative />}>
          <MenuItem {...menu}>Twitter</MenuItem>  
          <MenuItem {...menu}>Myspace</MenuItem>  
          <MenuItem {...menu}>Dribbble</MenuItem>  
        </MenuGroup>
        <MenuSeparator />
        <MenuGroup label="Search engines">
          <MenuItem {...menu}>Ecosia</MenuItem>  
          <MenuItem {...menu}>DuckDuckGo</MenuItem>  
        </MenuGroup>
      </Menu>
    </>
  );
};
render(
  <MenuGroupExample />
)

const PreferencesMenu = React.forwardRef((props, ref) => {
  const menu = useMenuState();
  return (
    <>
      <SubMenuButton ref={ref} {...menu} {...props}>
        Preferences
      </SubMenuButton>
      <Menu {...menu} aria-label="Preferences">
        <MenuItem {...menu}>Settings</MenuItem>
        <MenuItem {...menu} disabled>
          Extensions
        </MenuItem>
        <MenuSeparator {...menu} />
        <MenuItem {...menu}>Keyboard shortcuts</MenuItem>
      </Menu>
    </>
  );
});

const SubMenu = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="secondary">
        Code <ChevronDownIcon decorative />
      </MenuButton>
      <Menu {...menu} aria-label="Code">
        <MenuItem {...menu}>About Visual Studio Code</MenuItem>
        <MenuItem {...menu}>Check for Updates...</MenuItem>
        <MenuSeparator {...menu} />
        <MenuItem {...menu} as={PreferencesMenu} />
      </Menu>
    </>
  );
};

render(
  <SubMenu />
)

const PreferencesMenu = React.forwardRef((props, ref) => {
  const menu = useMenuState();
  return (
    <>
      <SubMenuButton ref={ref} {...menu} {...props}>
        Preferences
      </SubMenuButton>
      <Menu {...menu} aria-label="Preferences">
        <MenuItem {...menu}>Settings</MenuItem>
        <MenuItem {...menu} disabled>
          Extensions
        </MenuItem>
        <MenuSeparator {...menu} />
        <MenuItem {...menu}>Keyboard shortcuts</MenuItem>
      </Menu>
    </>
  );
});
const SubMenu = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="secondary">
        Code <ChevronDownIcon decorative />
      </MenuButton>
      <Menu {...menu} aria-label="Code">
        <MenuItem {...menu}>About Visual Studio Code</MenuItem>
        <MenuItem {...menu}>Check for Updates...</MenuItem>
        <MenuSeparator {...menu} />
        <MenuItem {...menu} as={PreferencesMenu} />
      </Menu>
    </>
  );
};
render(
  <SubMenu />
)

The MenuButton is the standard Paste Button with some extra functionality. As a result it takes all the usual props the Paste Button takes, meaning you have full access to all the variants and styling options.

For example, you can create an icon button menu trigger like so:

const IconExample = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="reset" size="reset">
        <MoreIcon decorative={false} title="More options" />
      </MenuButton>
      <Menu {...menu} aria-label="Preferences">
        <MenuItem {...menu}>Settings</MenuItem>
        <MenuItem {...menu} disabled>
          Extensions
        </MenuItem>
        <MenuSeparator {...menu} />
        <MenuItem {...menu}>Keyboard shortcuts</MenuItem>
      </Menu>
    </>
  );
};

render(
  <IconExample />
)

const IconExample = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="reset" size="reset">
        <MoreIcon decorative={false} title="More options" />
      </MenuButton>
      <Menu {...menu} aria-label="Preferences">
        <MenuItem {...menu}>Settings</MenuItem>
        <MenuItem {...menu} disabled>
          Extensions
        </MenuItem>
        <MenuSeparator {...menu} />
        <MenuItem {...menu}>Keyboard shortcuts</MenuItem>
      </Menu>
    </>
  );
};
render(
  <IconExample />
)

Composition notes#

Performing actions#

A menu item can perform 2 basic tasks:

trigger an action (switching a view between grid and list)
trigger a page navigation (going to a new page)

To do so, either set href with a valid url to go to a new page, or set the onClick as an event handler on the MenuItem.

const ActionsExample = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="secondary">
        Actions <ChevronDownIcon decorative />
      </MenuButton>
      <Menu {...menu} aria-label="Preferences">
        <MenuItem
          {...menu}
          onClick={e => {
            menu.hide();
            alert('do something');
          }}
        >
          Perform Action
        </MenuItem>
        <MenuItem {...menu} href="https://paste.twilio.design">Go to new page</MenuItem>
      </Menu>
    </>
  );
};

render(
  <ActionsExample />
)

const ActionsExample = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="secondary">
        Actions <ChevronDownIcon decorative />
      </MenuButton>
      <Menu {...menu} aria-label="Preferences">
        <MenuItem
          {...menu}
          onClick={e => {
            menu.hide();
            alert('do something');
          }}
        >
          Perform Action
        </MenuItem>
        <MenuItem {...menu} href="https://paste.twilio.design">Go to new page</MenuItem>
      </Menu>
    </>
  );
};
render(
  <ActionsExample />
)

Note

Menu item content is composible however you want. We'll have more complete best practice guidelines soon, but in the meantime here are some example compositions using Paste components.

const ItemsExample = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="primary">
        Menu item content <ChevronDownIcon decorative />
      </MenuButton>
      <Menu {...menu} aria-label="Preferences">
        <MenuItem  {...menu}>
        <MediaObject verticalAlign="center">
          <MediaFigure spacing="space20">
            <AttachIcon decorative={false} title="information" />
          </MediaFigure>
          <MediaBody>With left icon</MediaBody>
        </MediaObject>
      </MenuItem>
      <MenuItem  {...menu}>
        <MediaObject verticalAlign="center">
          <MediaBody>With right icon</MediaBody>
          <MediaFigure spacing="space20" align="end">
            <AttachIcon decorative={false} title="information" />
          </MediaFigure>
        </MediaObject>
      </MenuItem>
      <MenuItem  {...menu}>
        <MediaObject verticalAlign="center">
          <MediaFigure spacing="space20">
            <AttachIcon decorative={false} title="information" />
          </MediaFigure>
          <MediaBody>With two icons</MediaBody>
          <MediaFigure spacing="space20" align="end">
            <AttachIcon decorative={false} title="information" />
          </MediaFigure>
        </MediaObject>
      </MenuItem>
      <MenuItem  {...menu}>
        <MediaObject verticalAlign="center">
          <MediaFigure spacing="space20">
            <AttachIcon decorative={false} title="information" />
          </MediaFigure>
          <MediaBody>Keyboard shortcut?</MediaBody>
          <MediaFigure spacing="space20" align="end">
            <Text as="span" color="colorTextWeak" fontSize="fontSize20">
              ⌘+s
            </Text>
          </MediaFigure>
        </MediaObject>
      </MenuItem>
      </Menu>
    </>
  );
};

render(
  <ItemsExample />
)

const ItemsExample = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="primary">
        Menu item content <ChevronDownIcon decorative />
      </MenuButton>
      <Menu {...menu} aria-label="Preferences">
        <MenuItem  {...menu}>
        <MediaObject verticalAlign="center">
          <MediaFigure spacing="space20">
            <AttachIcon decorative={false} title="information" />
          </MediaFigure>
          <MediaBody>With left icon</MediaBody>
        </MediaObject>
      </MenuItem>
      <MenuItem  {...menu}>
        <MediaObject verticalAlign="center">
          <MediaBody>With right icon</MediaBody>
          <MediaFigure spacing="space20" align="end">
            <AttachIcon decorative={false} title="information" />
          </MediaFigure>
        </MediaObject>
      </MenuItem>
      <MenuItem  {...menu}>
        <MediaObject verticalAlign="center">
          <MediaFigure spacing="space20">
            <AttachIcon decorative={false} title="information" />
          </MediaFigure>
          <MediaBody>With two icons</MediaBody>
          <MediaFigure spacing="space20" align="end">
            <AttachIcon decorative={false} title="information" />
          </MediaFigure>
        </MediaObject>
      </MenuItem>
      <MenuItem  {...menu}>
        <MediaObject verticalAlign="center">
          <MediaFigure spacing="space20">
            <AttachIcon decorative={false} title="information" />
          </MediaFigure>
          <MediaBody>Keyboard shortcut?</MediaBody>
          <MediaFigure spacing="space20" align="end">
            <Text as="span" color="colorTextWeak" fontSize="fontSize20">
              ⌘+s
            </Text>
          </MediaFigure>
        </MediaObject>
      </MenuItem>
      </Menu>
    </>
  );
};
render(
  <ItemsExample />
)

Anatomy#

MenuButton#

See the button component.

Property	Default token	Modifiable?
background-color	color-background-body	No
border-width	border-width-10	No
border-color	color-border-light	No
border-radius	border-radius-20	No
box-shadow	shadow	No
max-width	size-30	No
min-width	size-20	No
padding-top	space-30	No
padding-bottom	space-30	No
z-index	z-index-20	No

SubMenuButton and MenuItem#

Default#

Property	Default token	Modifiable?
color	color-text (default) color-text-weaker (disabled)	No
padding-top	space-30	No
padding-bottom	space-30	No
padding-left	space-90 (in-group) or space-70 (regular)	No
padding-right	space-90 (in-group) or space-70 (regular)	No

Hover & focused#

Property	Default token	Modifiable?
color	color-text-link	No

MenuGroup#

Property	Default token	Modifiable?
padding-top	space-30	No
padding-bottom	space-30	No
padding-left	space-70	No
padding-right	space-70	No
color	color-text	No
font-weight	font-weight-bold	No

MenuSeparator#

See the separator component.

Property	Default token	Modifiable?
padding-top	space-40	No
padding-bottom	space-40	No

Usage Guide#

API#

Installation#

yarn add @twilio-paste/menu - or - yarn add @twilio-paste/core

Usage#

import {Menu, MenuButton, MenuItem, MenuSeparator, useMenuState} from '@twilio-paste/menu';
import {ChevronDownIcon} from '@twilio-paste/icons/esm/ChevronDownIcon';
const PreferencesMenu = () => {
  const menu = useMenuState();
  return (
    <>
      <MenuButton {...menu} variant="primary">
        Preferences <ChevronDownIcon decorative />
      </MenuButton>
      <Menu {...menu} aria-label="Preferences">
        <MenuItem {...menu}>Settings</MenuItem>
        <MenuItem {...menu} disabled>
          Extensions
        </MenuItem>
        <MenuSeparator {...menu} />
        <MenuItem {...menu}>Keyboard shortcuts</MenuItem>
      </Menu>
    </>
  );
};

Props#

useMenuState#

Pass these as part of an object to the useMenuState hook.

Prop	Type	Description
baseId	`string`	ID that will serve as a base for all the items IDs.
rtl	`boolean`
orientation	`horizontal, vertical, undefined`
currentId	`string, null, undefined`	The current focused item `id`.
loop	`boolean, horizontal, vertical`
wrap	`boolean, horizontal, vertical`
visible	`boolean`	Whether it's visible or not.
animated	`number, boolean`
placement	`auto-start, auto, auto-end, top-start, top, top-end, right-start, right, right-end, bottom-end, bottom, bottom-start, left-end, left, left-start`
gutter	`number, undefined`	Offset between the reference and the popover on the main axis. Should not be combined with `unstable_offset`.

useMenuState returned props#

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

Prop	Type	Description
baseId	`string`	ID that will serve as a base for all the items IDs.
baseId	string	ID that will serve as a base for all the items IDs.
visible	boolean	Whether it's visible or not.
animated	number \| boolean
modal	boolean	Toggles Dialog's `modal` state.
animating	boolean	Whether it's animating or not.
stopAnimation	() => void	Stops animation. It's called automatically if there's a CSS transition.
hide	() => void	Changes the `visible` state to `false`
placement	"auto-start" \| "auto" \| "auto-end" \| "top-start...	Actual `placement`.
orientation	"horizontal" \| "vertical" \| undefined	Defines the orientation of the composite widget.
currentId	string \| null \| undefined	The current focused item `id`.
wrap	boolean \| "horizontal" \| "vertical"	If enabled, moving to the next item from the last one in a row or column will focus the first item in the next row or column and vice-versa.
groups	Group[]	Lists all the composite groups with their `id` and DOM `ref`.
items	Item[]	Lists all the composite items with their `id`, DOM `ref`, `disabled` state and `groupId` if any.
setCurrentId	(value: SetStateAction<string \| null \| undefine...	Sets `currentId`.
first	() => void	Moves focus to the first item.
last	() => void	Moves focus to the last item.
move	(id: string \| null) => void	Moves focus to a given item ID.
next	(unstable_allTheWay?: boolean \| undefined) => void	Moves focus to the next item.
previous	(unstable_allTheWay?: boolean \| undefined) => void	Moves focus to the previous item.

Prop	Type	Description	Default
hideOnClickOutside	`boolean, undefined`	When enabled, user can hide the dialog by clicking outside it.
disabled	`boolean, undefined`	Same as the HTML attribute.

MenuArrow#

Prop	Type	Description	Default
size	`string, number, undefined`

MenuButton#

Prop	Type	Description	Default
disabled	`boolean, undefined`	Same as the HTML attribute.

MenuDisclosure#

Prop	Type	Description	Default
disabled	`boolean, undefined`	Same as the HTML attribute.

MenuGroup#

Prop	Type	Description	Default
label	`string`	Names the grouping
icon	`React.ReactNode`	One of our icon components. Must be decorative.

MenuItem#

Prop	Type	Description
disabled	`boolean, undefined`	Same as the HTML attribute.
id	`string, undefined`	Same as the HTML attribute.
onClick	`() => void`	Same as the HTML attribute.
href	`string, undefined`	Same as the HTML attribute.

MenuItemCheckbox#

Prop	Type	Description
disabled	`boolean, undefined`	Same as the HTML attribute.
value	`string, number, undefined`	Checkbox's value is going to be used when multiple checkboxes share the same state. Checking a checkbox with value will add it to the state array.
checked	`boolean, undefined`	Checkbox's checked state. If present, it's used instead of `state`.
id	`string, undefined`	Same as the HTML attribute.
name	`string`	MenuItemCheckbox's name as in `menu.values`.

MenuItemRadio#

Prop	Type	Description
disabled	`boolean, undefined`	Same as the HTML attribute.
value	`string, number, undefined`	Checkbox's value is going to be used when multiple checkboxes share the same state. Checking a checkbox with value will add it to the state array.
checked	`boolean, undefined`	Checkbox's checked state. If present, it's used instead of `state`.
id	`string, undefined`	Same as the HTML attribute.
name	`string`	MenuItemRadio's name as in `menu.values`.

Menu

Using alpha components in your product

Guidelines.css-1p5xx02{-webkit-text-decoration:none;text-decoration:none;margin-left:0.5rem;color:rgb(96,107,133);}.css-1p5xx02:hover{-webkit-text-decoration:underline;text-decoration:underline;}#

About Menu#

Do not nest multiple actions within a menu item

Examples#

Basic menu#

Menu with groups#

Menu with sub items#

Choosing a menu trigger#

Composition notes#

Performing actions#

Composing menu items#

Note

Anatomy#

MenuButton#

Menu#

SubMenuButton and MenuItem#

Default#

Hover & focused#

MenuGroup#

MenuSeparator#

Usage Guide#

API#

Installation#

Usage#

Props#

useMenuState#

useMenuState returned props#

Menu#

MenuArrow#

MenuButton#

MenuDisclosure#

MenuGroup#

MenuItem#

MenuItemCheckbox#

MenuItemRadio#

7.0.0#

Patch Changes#

6.0.1#

Patch Changes#

6.0.0#

Patch Changes#

5.0.1#

Patch Changes#

5.0.0#

Patch Changes#

4.0.3#

Patch Changes#

4.0.2#

Patch Changes#

4.0.1#

Patch Changes#

4.0.0#

Patch Changes#

3.0.1#

Patch Changes#

3.0.0#

Patch Changes#

2.1.1link takes you to an external page (2021-01-25)

Features#

2.0.6link takes you to an external page (2021-01-15)

2.0.5link takes you to an external page (2021-01-14)

2.0.4link takes you to an external page (2021-01-14)

2.0.3link takes you to an external page (2021-01-13)

2.0.2link takes you to an external page (2021-01-07)

2.0.1link takes you to an external page (2020-12-17)

Bug Fixes#

BREAKING CHANGES#

1.1.54link takes you to an external page (2020-12-15)

1.1.53link takes you to an external page (2020-12-11)

1.1.52link takes you to an external page (2020-12-11)

1.1.51link takes you to an external page (2020-12-09)

1.1.50link takes you to an external page (2020-12-03)

1.1.49link takes you to an external page (2020-12-02)

1.1.48link takes you to an external page (2020-11-19)

1.1.47link takes you to an external page (2020-11-16)

1.1.46link takes you to an external page (2020-11-11)

1.1.45link takes you to an external page (2020-11-10)

1.1.44link takes you to an external page (2020-11-09)

Guidelines#

2.1.1 (2021-01-25)

2.0.6 (2021-01-15)

2.0.5 (2021-01-14)

2.0.4 (2021-01-14)

2.0.3 (2021-01-13)

2.0.2 (2021-01-07)

2.0.1 (2020-12-17)

1.1.54 (2020-12-15)

1.1.53 (2020-12-11)

1.1.52 (2020-12-11)

1.1.51 (2020-12-09)

1.1.50 (2020-12-03)

1.1.49 (2020-12-02)

1.1.48 (2020-11-19)

1.1.47 (2020-11-16)

1.1.46 (2020-11-11)

1.1.45 (2020-11-10)

1.1.44 (2020-11-09)

1.1.43 (2020-11-06)

1.1.42 (2020-11-05)

1.1.41 (2020-11-02)

1.1.40 (2020-10-30)

1.1.39 (2020-10-29)

1.1.38 (2020-10-23)

1.1.37 (2020-10-22)

1.1.36 (2020-10-21)

1.1.35 (2020-10-19)

1.1.34 (2020-10-15)

1.1.33 (2020-10-13)

1.1.32 (2020-10-09)

1.1.31 (2020-10-07)

1.1.30 (2020-10-07)

1.1.29 (2020-10-07)

1.1.28 (2020-10-07)

1.1.27 (2020-09-28)

1.1.26 (2020-09-25)

1.1.25 (2020-09-23)

1.1.24 (2020-09-22)

1.1.23 (2020-09-21)

1.1.22 (2020-09-15)

1.1.21 (2020-09-15)

1.1.20 (2020-09-14)

1.1.19 (2020-09-10)

1.1.18 (2020-09-09)

1.1.17 (2020-09-09)

1.1.16 (2020-09-08)

1.1.15 (2020-09-08)

1.1.14 (2020-09-03)

1.1.13 (2020-09-02)

1.1.12 (2020-09-02)

1.1.11 (2020-08-31)

1.1.10 (2020-08-31)

1.1.9 (2020-08-31)

1.1.8 (2020-08-27)

1.1.7 (2020-08-24)

1.1.6 (2020-08-24)

1.1.5 (2020-08-19)

1.1.4 (2020-08-12)

1.1.3 (2020-08-12)

1.1.2 (2020-08-12)

1.1.1 (2020-08-12)

1.0.1 (2020-08-06)

0.2.6 (2020-08-04)

0.2.5 (2020-08-04)

0.2.4 (2020-07-31)

0.2.3 (2020-07-30)

0.2.2 (2020-07-29)

0.2.1 (2020-07-28)

0.1.26 (2020-07-22)

0.1.25 (2020-07-20)

0.1.24 (2020-07-15)

0.1.23 (2020-07-14)

0.1.22 (2020-07-14)

0.1.21 (2020-07-02)

0.1.20 (2020-07-02)

0.1.19 (2020-07-01)

0.1.18 (2020-07-01)

0.1.17 (2020-06-29)

0.1.16 (2020-06-25)