Menu - Web

For development, import Menu from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Menu consists of four primary elements that work together to provide users with an actionable list of options.

Trigger
Popover
Menu item
Nested Menu item

Options

The Menu supports flat and nested configurations to accommodate various action list scenarios.

Flat

Nested

Behavior

The Menu responds to user interaction with distinct visual states and synchronized focus and hover behaviors.

Visual States

Default

Hover

Disabled

Focusing

Focus and hover states are synchronized. Moving the mouse over a menu item will automatically set focus to that item. Similarly, navigating through the menu with keyboard focus will trigger the hover state on the focused item.

Usage Guidelines

Standard	Requirement
DoProvide multiple actions	Use the Menu to provide multiple actions to the user.
Don’tReplace a few Buttons that fit	Use individual Buttons when there are fewer than five actions and they fit in the available space. Page Header is an exception to this, as it explicitly disallows this.

Alternatives

The Menu is used to perform actions on the page, and sometimes also a navigational context. The Combobox is used for choosing an option amongst a list, usually in the context of a Form. When a list of actions need to take place, the Menu should be used. It is not recommended to recreate menu-like interactions through a Popover.

How to Use

Parent and Children

Menu trigger should have direct relationship to its children. This also applies to the nested version of the Menu.

Nested menu example

Disabled Handling

When an action is temporarily unavailable, use disabled state
When a user does not have the credentials to take action, do not display these unavailable actions to them. This avoids cluttering the UI and confusing the user when they are unable to take action. When a component is disabled, it is not interactive, meaning tooltips are not available to inform more.

Grouping

Menu does not allow for grouping. To group elements, use the Nested Menu.

Content

Content within the Menu should clearly communicate each action through descriptive labels. For content guidance, refer to the content guidance provided in the Button.

Keyboard Interaction

Users can navigate the Menu using standard keyboard controls.

Trigger

Key	Interaction
Enter/Space	Opens the menu and places focus on the first menu item.
Arrow Down	Opens the menu and moves focus to the first menu item.
Arrow up	Opens the menu and moves focus to the last menu item.

Key	Interaction
Arrow Down	Focuses next menu item.
Arrow Up	Focuses previous menu item.
Arrow Right	If nested, opens the nested menu and places focus on the first nested menu item.
Arrow Left	If focus is inside nested menu, closes the nested menu and places focus on the root menu item.

Code

Implementation
Default Menu Props
Custom Trigger Props
TriggerReturnProps
Menu.Item Props

Common Examples

import { Menu } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <Menu label="Click me!">
      <Menu.Item label="Item 1" />
      <Menu.Item label="Item 2" />
      <Menu.Item label="Item 3" />
    </Menu>
  );
}

The Menu and Menu.Item components can be used to compose basic dropdown menus.

Nesting menus in dropdowns

To create nested dropdown menus, simply add a Menu as a child of another Menu.To use a custom trigger element, use the trigger prop of the Menu, and omit the label prop (and any other prop meant to be passed to the default Button trigger).Nested menus support the trigger prop the same way root menus do. Spread all props onto your trigger element, including ref, className, and data-anv, so the nested item receives menu styling and participates in keyboard navigation. A custom trigger replaces the default nested button, including the submenu chevron — include that icon in your markup.

React Accessibility

When using a custom trigger, make sure that the trigger:

Can receive focus via keyboard when tabbing.
Opens the menu when the user presses enter.
Closes the menu and returns focus to the trigger when the user presses escape.

Nested custom triggers also need:

role, data-anv, and tabIndex spread onto the element so the parent menu’s focus query includes them.
ArrowRight to open the submenu.
ArrowLeft to close the submenu and return focus to the nested trigger.

For more guidance on accessible menu interactions, see keyboard navigation and focus management best practices.

<Menu
  label="Click me!"
  open={false}
  disableAutoHeight={false}
  appearance="secondary"
  size="medium"
>
  <Menu.Item label="Item 1" />
  <Menu.Item label="Item 2" />
</Menu>

Use the trigger prop to determine what element should open the menu. If trigger is omitted, a Button is used as the trigger by default. In this case, all props available to the Button component can be used on the Menu. In addition, the following props are available:

string

Alternatively, aria-label or aria-labelledby can be used.

boolean

This will stop the menu from automatically deciding which way to open based on the trigger’s location on the screen.

boolean

<Menu
  trigger={(props) => <CustomButton {...props}>Custom Trigger</CustomButton>}
  open={false}
  disableAutoHeight={false}
>
  <Menu.Item label="Item 1" />
  <Menu.Item label="Item 2" />
</Menu>

When using the trigger prop to render a custom trigger, the following props are available:

boolean

This will stop the menu from automatically deciding which way to open based on the trigger’s location on the screen.

boolean

(TriggerReturnProps) => ReactElement

<Menu
  trigger={({ ref, ...rest }) => (
    <button type="button" {...rest} ref={ref}>
      Custom Trigger
    </button>
  )}
>
  <Menu.Item label="Item 1" />
</Menu>

`TriggerReturnProps`

The following props are passed as an object parameter to the trigger callback, on both root and nested menus. The function returns a ReactElement, and every prop must be spread onto that element (see Creating custom menu triggers).

Each prop below is optional, so omitting one still compiles. On a nested menu, role, data-anv, and tabIndex are what the parent menu’s focus query matches on — a trigger missing them is skipped by keyboard navigation.

"open" | "close"

required

Whether the menu the trigger controls is currently open.

string

Identifies the element (or elements) whose contents or presence are controlled by the current element.

boolean | "true" | "false"

Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.

Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.

string

Applies the menu item styling. Nested menus only.

"menu-item"

Marks the trigger as a focusable menu item. Nested menus only.

boolean

string

(e: FocusEvent<HTMLElement>) => void

() => void

(e: FocusEvent<HTMLElement>) => void

(e: KeyboardEvent<HTMLElement>) => void

(e: MouseEvent<HTMLElement>) => void

Ref<HTMLButtonElement>

"menuitem"

Nested menus only.

number

Roving tab index — 0 while the item is focused, -1 otherwise. Nested menus only.

<Menu.Item
  label="Menu Item"
  disabled={false}
  icon={EditIcon}
  onClick={() => console.log("Clicked")}
/>

In addition to the props listed below, the Menu.Item component can accept any valid HTML button props.

ReactNode

required

boolean

default:"false"

Svg

The SVGR library imports *.svg files as React components, so icon accepts a React component.

Concepts & Guidelines

Anvil2

Resources

Menu - Web

Anatomy

Options

Flat

Nested

Behavior

Visual States

Default

Hover

Disabled

Focusing

Usage Guidelines

Alternatives

Menu vs Combobox

Menu vs Popover

How to Use

Parent and Children

Disabled Handling

Grouping

Content

Keyboard Interaction

Trigger

Menu Item

Code

Common Examples

Nesting menus in dropdowns

Creating custom menu triggers

Creating custom nested menu triggers

React Accessibility

Default `Menu` Props

Custom Trigger `Menu` Props

`TriggerReturnProps`

`Menu.Item` Props

​Anatomy

​Options

​Flat

​Nested

​Behavior

​Visual States

​Default

​Hover

​Disabled

​Focusing

​Usage Guidelines

​Alternatives

​Menu vs Combobox

​Menu vs Popover

​How to Use

​Parent and Children

​Disabled Handling

​Grouping

​Content

​Keyboard Interaction

​Trigger

​Menu Item

​Code

​Common Examples

​Creating simple dropdown menus

​Nesting menus in dropdowns

​Creating custom menu triggers

​Creating custom nested menu triggers

​React Accessibility

​Default Menu Props

​Custom Trigger Menu Props

​TriggerReturnProps

​Menu.Item Props

Anatomy

Options

Flat

Nested

Behavior

Visual States

Default

Hover

Disabled

Focusing

Usage Guidelines

Alternatives

Menu vs Combobox

Menu vs Popover

How to Use

Parent and Children

Disabled Handling

Grouping

Content

Keyboard Interaction

Trigger

Menu Item

Code

Common Examples

Creating simple dropdown menus

Nesting menus in dropdowns

Creating custom menu triggers

Creating custom nested menu triggers

React Accessibility

Default `Menu` Props

Custom Trigger `Menu` Props

`TriggerReturnProps`

`Menu.Item` Props