Menu API

Import

Cimpress UI exports five menu-related components:

MenuRoot: component that connects a trigger button with its associated menu
Menu: component that displays a collapsible list of options and actions that users can choose from.
MenuItem: component that renders a single interactive item within a menu.
MenuSection: component that groups related menu items together under a section title.
Divider: component that adds a horizontal line between menu items to visually separate them.

import { Divider, Menu, MenuItem, MenuRoot, MenuSection } from '@cimpress-ui/react';

Accessibility notes

Menu trigger button follows the ARIA menu button pattern. See the linked page for a list of available keyboard interactions.

Collapsible menu list follows the ARIA menu pattern. See the linked page for a list of available keyboard interactions.

Menu trigger button requires a textual label to remain accessible to assistive technologies. See our accessibility guide for more details.

To open a menu when a trigger button is pressed, wrap both the trigger button and the menu component with a MenuRoot component. This will automatically associate the button with the menu, without any manual setup.

Preview
Code

import { Button, Menu, MenuItem, MenuRoot } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <MenuRoot>
      <Button>Open menu</Button>
      <Menu aria-label="Menu">
        <MenuItem>A menu can be opened by an automatically attached trigger button.</MenuItem>
      </Menu>
    </MenuRoot>
  );
}

Selectable items

Menu items can be made selectable. Both single and multiple selection is supported. Each menu section has its own selection state.

Preview
Code

import { Button, Menu, MenuItem, MenuRoot, MenuSection, type Selection } from '@cimpress-ui/react';
import {
  IconChevronDown,
  IconTextAlignmentCenter,
  IconTextAlignmentLeft,
  IconTextAlignmentRight,
  IconTextBold,
  IconTextItalic,
  IconTextStrikethrough,
  IconTextUnderline,
} from '@cimpress-ui/react/icons';
import { useState } from 'react';

const TEXT_STYLE_ITEMS = [
  { id: 'bold', label: 'Bold', icon: <IconTextBold /> },
  { id: 'italic', label: 'Italic', icon: <IconTextItalic /> },
  { id: 'underline', label: 'Underline', icon: <IconTextUnderline /> },
  { id: 'strikethrough', label: 'Strikethrough', icon: <IconTextStrikethrough /> },
];

const TEXT_ALIGNMENT_ITEMS = [
  { id: 'left', label: 'Left', icon: <IconTextAlignmentLeft /> },
  { id: 'center', label: 'Center', icon: <IconTextAlignmentCenter /> },
  { id: 'right', label: 'Right', icon: <IconTextAlignmentRight /> },
];

export default function Demo() {
  const [selectedTextStyles, setSelectedTextStyles] = useState<Selection>(() => new Set(['bold', 'italic']));
  const [selectedTextAlignment, setSelectedTextAlignment] = useState<Selection>(() => new Set(['left']));

  return (
    <MenuRoot>
      <Button iconEnd={<IconChevronDown />}>Text formatting</Button>
      <Menu>
        <MenuSection
          title="Style"
          items={TEXT_STYLE_ITEMS}
          selectionMode="multiple"
          selectedKeys={selectedTextStyles}
          onSelectionChange={setSelectedTextStyles}
        >
          {(item) => <MenuItem icon={item.icon}>{item.label}</MenuItem>}
        </MenuSection>
        <MenuSection
          title="Alignment"
          items={TEXT_ALIGNMENT_ITEMS}
          selectionMode="single"
          selectedKeys={selectedTextAlignment}
          onSelectionChange={setSelectedTextAlignment}
        >
          {(item) => <MenuItem icon={item.icon}>{item.label}</MenuItem>}
        </MenuSection>
      </Menu>
    </MenuRoot>
  );
}

Collections

Menu is a collection component. See our collection components guide to learn how to work with collections.

API reference

MenuRoot

Encapsulates a menu trigger and its associated menu. The trigger can be any Cimpress UI button, and the menu will be displayed when the trigger is activated.

See menu usage guidelines.

MenuRootProps

children * Section titled “ children * ” ReactNode: The menu trigger with its associated menu. Provide the trigger as the first child, and the menu as the second child.
isOpen Section titled “ isOpen ” boolean: Whether the overlay is open by default (controlled).
defaultOpen Section titled “ defaultOpen ” boolean: Whether the overlay is open by default (uncontrolled).
onOpenChange Section titled “ onOpenChange ” (isOpen: boolean) => void: Handler that is called when the overlay's open state changes.

Displays a collapsible list of options and actions that users can choose from.

MenuProps<T extends CollectionItem = CollectionItem>

align Section titled “ align ” 'end' | 'start': The alignment of the menu overlay relative to its trigger.

Defaults to 'start' .
onAction Section titled “ onAction ” (key: Key) => void: Handler that is called when an item is selected. When using onAction, all items must have an id prop defined.
onScroll Section titled “ onScroll ” UIEventHandler<HTMLDivElement>: Handler that is called when the list of items is scrolled.
children Section titled “ children ” ReactNode | ((item: T) => ReactNode): The contents of the collection.
items Section titled “ items ” Iterable<T, any, any>: The items to display in the collection.
selectionMode Section titled “ selectionMode ” SelectionMode: The type of selection that is allowed in the collection.
selectedKeys Section titled “ selectedKeys ” 'all' | (Iterable<Key, any, any>): The currently selected keys in the collection (controlled).
onSelectionChange Section titled “ onSelectionChange ” (keys: Selection) => void: Handler that is called when the selection changes.

MenuItem

Renders a single list item within Menu.

MenuItemProps

children * Section titled “ children * ” StringLikeChildren: The content to display as the label.
id Section titled “ id ” Key: The ID of the item. Has to be unique across all sections and items.
description Section titled “ description ” string: Additional description for the menu item.
icon Section titled “ icon ” ReactNode: An icon representing the menu item.
href Section titled “ href ” string: A URL to link to.
routerOptions Section titled “ routerOptions ” undefined: Options for the configured client side router.
hrefLang Section titled “ hrefLang ” string: Hints at the human language of the linked URL. SeeMDN.
target Section titled “ target ” HTMLAttributeAnchorTarget: The target window for the link. See MDN.
rel Section titled “ rel ” string: The relationship between the linked resource and the current page. See MDN.
download Section titled “ download ” string | boolean: Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
ping Section titled “ ping ” string: A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy Section titled “ referrerPolicy ” HTMLAttributeReferrerPolicy: How much of the referrer to send when following the link. See MDN.
onHoverStart Section titled “ onHoverStart ” (e: HoverEvent) => void: Handler that is called when a hover interaction starts.
onHoverEnd Section titled “ onHoverEnd ” (e: HoverEvent) => void: Handler that is called when a hover interaction ends.
isDisabled Section titled “ isDisabled ” boolean: Whether the item is disabled.
onAction Section titled “ onAction ” () => void: Handler that is called when the item is selected.

MenuSection

Groups list items within Menu into a section.

MenuSectionProps<T extends CollectionItem = CollectionItem>

title * Section titled “ title * ” string: The content to display as the section title.
id Section titled “ id ” Key: The ID of the section. Has to be unique across all sections and items.
children Section titled “ children ” ReactNode | ((item: T) => ReactNode): The contents of the collection.
items Section titled “ items ” Iterable<T, any, any>: The items to display in the collection.
selectionMode Section titled “ selectionMode ” SelectionMode: The type of selection that is allowed in the collection.
selectedKeys Section titled “ selectedKeys ” 'all' | (Iterable<Key, any, any>): The currently selected keys in the collection (controlled).
onSelectionChange Section titled “ onSelectionChange ” (keys: Selection) => void: Handler that is called when the selection changes.

Divider

Renders a divider between adjacent content.

ref Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

DividerProps

orientation Section titled “ orientation ” 'vertical' | 'horizontal': The orientation of the divider (horizontal or vertical).

Defaults to 'horizontal' .
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

Menu API

Import

Accessibility notes

Triggering a menu

Selectable items

Collections

API reference

MenuRoot

children *

isOpen

defaultOpen

onOpenChange

Menu

align

onAction

onScroll

children

items

selectionMode

selectedKeys

onSelectionChange

MenuItem

children *

id

description

icon

href

routerOptions

hrefLang

target

rel

download

ping

referrerPolicy

onHoverStart

onHoverEnd

isDisabled

onAction

MenuSection

title *

id

children

items

selectionMode

selectedKeys

onSelectionChange

Divider

ref

orientation

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft