Menu

Anatomy

1. Container: Rectangular container that houses the icon and text for menu list items.
2. Text: Text for indicating where the link leads to when the menu is clicked on. Text can overflow to the next line but avoid going over more than two lines of text.
3. Icons: Icons are optional and can be positioned before or after the text.

Usage Guidance

• Popup Menus can appear next to, in front of, above, or below the element that launched them, such as Dropdown Buttons, Dropdown Icons, icon only Primary/Secondary/Tertiary Button variants or by right-clicking a contextual item.
• Popup Menus should overlap and visually look like they are in front of other UI elements. They should always be positioned within the viewable areas of the screen and be 8px away from the element that launched them.
• Popup Menus should always contain a list of menu selections, which are options users can choose from. The list should be scannable, kept as concise as possible, and written in title case instead of sentences.
• Consider how important each option is. The list of options should be sorted in a logical order, such as alphabetical, chronological, order of importance, and so on.

When to Use

• In most cases, as with Overflow Menus, where there aren't enough space on screen to show all the actions, there could be between 1-7 items to choose from. However, there shouldn't be more than 15 items listed at once on a single Popup Menu.
• When users must make a single selection from the list of options.

When to Use Something Else

• Consider using a Switch if the only options are yes or no.
• For a list between 2 to 7 predefined options, consider using a Radio input to select one option or Checkboxes to select multiple options. Radio and Checkbox groups display all options upfront and do not require the user to interact with the input to view the list of options.
• Use a Prompt when the number of list items is large or unknown. Prompts have search capabilities and folders which provide users with the means to browse options. Prompts can be configured to support single or multi-select.

Examples

Basic Example

Menu is typically triggered by an action such as pressing a button. The Menu comes with a Target subcomponent and a Popup.

Menu will automatically focus on the cursor item (first item by default). The Menu uses a menu model which composes a list model and a popup model and sets up accessibility features for you.

Menu follows the Actions Menu pattern using roving tabindex. Below is table of supported keyboard shortcuts and associated actions.

Context Menu

Icons

Component API

Menu

Usage

Menu is a combination of as popup and a list. It usually has some type of target element that expands/collapses the menu and a menu role and and several menuitem roles. Focus is managed uses roving tabindex for maximum compatibility. A Menu can have two modes: single and multiple. This mode determines both how many items can be selected as well as the default behavior when a menuitem is clicked. For the single mode, selecting a menuitem will select and close the menu. For the multiple mode, clicking a menuitem will toggle selection and will not close the menu.

Props

Usage

Like all compound components, the Menu component is a container component. It is responsible for putting a MenuModel in the React context for all the menu subcomponents. You can either pass this component model config or a "hoisted" model.

With model config:

<Menu mode="multiple">{/* Child components */}</Menu>

With a hoisted model:

const model = useMenuModel({
  mode: 'multiple',
});

// we now have access to `model.state` and `model.events`

<Menu model={model}>{/* Child components */}</Menu>;

Menu.Target

Usage

Menu.Target is similar to all Popup.Target types. The component only provides behavior and no styling. The as prop is used to determine which component is rendered. This component should forward the ref and apply any additional props directly to an element. The default as is a SecondaryButton. Any Canvas Kit component should work with an as.

An example changing to a PrimaryButton

<Menu.Target as={PrimaryButton}>Primary Button Text</Menu.Target>

This element will apply aria-haspopup and aria-expanded to inform screen readers there's a popup associated with the element.

Props

Undocumented props are spread to the element provided by the as which is a SecondaryButton by default.

Specifications

Accessibility Guidelines

• When the Menu is displayed, the focus should move onto the first option in the Menu.
• The Menu as a whole should only receive one focus stop on each list item.
• Up and down arrows must be used to navigate the Menu.

Content Guidelines

• When writing Menu list items, refer to the Menus section of the Content Style Guide.