Menu - Web (AI Kit)

For development, import Menu from @servicetitan/anvil2-ai-kit. For design, find it in the AI Kit Web Component Library file.

Options

The Menu supports an action mode and two persisted selection modes, leading icons, disabled options, and either edge of its trigger for the popover.

Selection Mode

selectionMode switches the menu between three behaviors: "none" (the default) is a plain action menu; "single" and "multiple" persist a checked selection instead of closing on pick.

Single Select

selectionMode="single" behaves like a “sort by” control: picking an option checks it, unchecks any other, and closes the menu to confirm the single choice.

Multi Select

selectionMode="multiple" lets several options stay checked at once, and the menu stays open after a pick so more can be toggled. The hero example above is an action menu — selectionMode’s default, "none". Each option runs a command via onAction and the menu closes immediately on pick. Action menus and the selection modes render identically at rest; the difference is entirely behavioral — whether picking an option persists a checked state or fires a one-off command.

Icons

An optional leading icon renders at 16px before the label. Icons are decorative and don’t contribute to the option’s accessible name.

Disabled Options

A disabled option can’t be focused, selected, or activated, and renders dimmed — including an option that is already selected; the dimmed check still shows its state.

Placement

placement opens the popover on the "bottom" (default, shown in the hero example above) or "top" edge of the trigger, with the same 4px gap either way.

Behavior

The popover hugs its content between a 180px floor and a 360px ceiling, and every option responds to hover, focus, press, and disabled states.

Visual States

Unselected options stay neutral — a subtle gray fill on hover and press, with unchanged text. Selected options use the informative-blue family instead. Keyboard focus draws a ring only, with no background fill. Disabled options render dimmed regardless of selection.

Wrapping

Labels wrap to multiple lines once the popover reaches its 360px max-width, rather than growing the popover without bound.

Scrolling List

Enough options to exceed the popover’s available height scroll internally; the scroll region shares the popover’s corner radius so its scrollbar stays clipped to the rounded shape.

Usage Guidelines

When to Use

Use the Menu when:

Running a command from a trigger – Each option runs a command or navigates to a destination, and the menu closes on pick.
Choosing one option, such as a sort order – Use single selection. Picking an option checks it and closes the menu.
Toggling several options at once – Use multiple selection. The menu stays open so the user can check more options.

When not to use

Avoid using the Menu for:

Showing options that stay visible on the page – Use the Checkbox instead.
Listing prior conversations – Use the Chat History instead.

Keyboard Interaction

Users can open, navigate, and act on the Menu using standard keyboard controls.

Key	Description
Enter / Space / Down Arrow	Opens the menu from the trigger, focusing the first option
Up / Down Arrow	Moves focus between options
Typeahead	Jumps focus to the next option starting with the typed character(s)
Enter / Space	Activates or toggles the focused option
Escape	Closes the menu and returns focus to the trigger

Code

Implementation
Menu Props
MenuOption

Common Examples

To use the Menu, pass a Carto Button through trigger and configured MenuOption objects through items. The kit forbids composed menu-item children.

import { Button, Menu } from "@servicetitan/anvil2-ai-kit";

function ExampleComponent() {
  return (
    <Menu
      trigger={<Button label="Options" variant="secondary" />}
      items={[
        { id: "rename", label: "Rename", onAction: rename },
        { id: "delete", label: "Delete", onAction: remove },
      ]}
    />
  );
}

Selection

The default selectionMode="none" creates an action menu that closes after activation. Use "single" or "multiple" for persistent checked selections.

Icons and disabled options

Pass an icon from @servicetitan/anvil2-icons through an option’s icon field. Set isDisabled on an option to prevent focus, selection, and activation.

Link options

Pass href to render an option as a navigation link. An option with target="_blank" receives a safe rel default and a localized new-tab announcement.

Placement and long lists

placement opens the popover above or below its trigger with a fixed 4px gap. Long labels wrap at the 360px width ceiling, and long lists scroll within available viewport height.

Internationalization

Menu option labels are consumer content and must be localized before they are passed in items. External link options use ai-kit.menu.opensInNewTab for the hidden new-tab announcement.

<AiKitIntlProvider
  messages={{
    "ai-kit.menu.opensInNewTab": "(opens in a separate tab)",
  }}
>
  <Menu
    trigger={<Button label="Help" />}
    items={[
      {
        id: "docs",
        label: "Documentation",
        href: "https://example.com",
        target: "_blank",
      },
    ]}
  />
</AiKitIntlProvider>

React Accessibility

React Aria supplies keyboard navigation, typeahead, focus management, and selection semantics.
Arrow keys move between options. Enter or Space activates the focused option. Escape closes the menu and restores focus to the trigger.
External link options include a localized hidden new-tab announcement.

<Menu
  trigger={<Button label="Options" />}
  items={[{ id: "rename", label: "Rename" }]}
  placement="bottom"
  selectionMode="none"
/>

The Menu accepts the following props and forwards remaining React Aria MenuTrigger and Menu props except their composed children and render slots.

MenuOption[]

required

Options to render from top to bottom.

ReactElement<ButtonProps>

required

Carto Button that opens the menu.

string

Class merged onto the popover surface.

boolean

Whether the menu starts open when uncontrolled.

boolean

Controlled open state. Pair with onOpenChange.

(isOpen: boolean) => void

Called when the menu’s open state changes.

(keys: Selection) => void

Called when selected option keys change.

"top" | "bottom"

default:"bottom"

Side where the popover opens relative to its trigger.

Selection

Controlled selected option keys.

"none" | "single" | "multiple"

default:"none"

"none" creates an action menu. "single" and "multiple" persist checked selection.

const option: MenuOption = {
  id: "rename",
  label: "Rename",
  icon: <IconPencil />,
  onAction: rename,
};

`MenuOption`

MenuOption extends React Aria MenuItem props with configured content.

Key

required

Selection key reported through the menu’s selection APIs.

string

required

Visible label and accessible name.

Href

Destination that renders the option as a navigation link.

IconElement

Leading icon rendered before the label.

boolean

Prevents focus, selection, and activation.

() => void

Handles activation for an action option.

string

Link target. "_blank" adds the localized new-tab announcement.

Concepts & Guidelines

Anvil2

Resources

Menu - Web (AI Kit)

Options

Selection Mode

Single Select

Multi Select

Action Menu

Icons

Disabled Options

Placement

Behavior

Visual States

Wrapping

Scrolling List

Usage Guidelines

When to Use

When not to use

Keyboard Interaction

Code

Common Examples

Selection

Icons and disabled options

Link options

Placement and long lists

Internationalization

React Accessibility

`Menu` Props

`MenuOption`

​Options

​Selection Mode

​Single Select

​Multi Select

​Action Menu

​Icons

​Disabled Options

​Placement

​Behavior

​Visual States

​Wrapping

​Scrolling List

​Usage Guidelines

​When to Use

​When not to use

​Keyboard Interaction

​Code

​Common Examples

​Selection

​Icons and disabled options

​Link options

​Placement and long lists

​Internationalization

​React Accessibility

​Menu Props

​MenuOption

Options

Selection Mode

Single Select

Multi Select

Action Menu

Icons

Disabled Options

Placement

Behavior

Visual States

Wrapping

Scrolling List

Usage Guidelines

When to Use

When not to use

Keyboard Interaction

Code

Common Examples

Selection

Icons and disabled options

Link options

Placement and long lists

Internationalization

React Accessibility

`Menu` Props

`MenuOption`