Skip to contentSkip to navigationSkip to topbar
Paste
FigmaStar

Menu

Version 14.1.1GithubStorybookPeer review pending

A Menu is a button that presents a list of items that users can choose to trigger an action.

Installation

Installation page anchor
yarn add @twilio-paste/menu - or - yarn add @twilio-paste/core

Usage

Usage page anchor
import {Menu, MenuButton, MenuItem, MenuSeparator, useMenuState} from '@twilio-paste/core/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

Props page anchor
MenuInitialState page anchor

MenuStateReturn page anchor

animated RequiredRequired

If true, animating will be set to true when visible is updated. It'll wait for stopAnimation to be called or a CSS transition ends. If animated is set to a number, stopAnimation will be called only after the same number of milliseconds have passed.

Type
number | boolean

animating RequiredRequired

Whether it's animating or not.

Type
boolean

baseId RequiredRequired

ID that will serve as a base for all the items IDs.

Type
string

down RequiredRequired

Moves focus to the item below.

Type
(unstable_allTheWay?: boolean | undefined) => void

first RequiredRequired

Moves focus to the first item.

Type
() => void

groups RequiredRequired

Lists all the composite groups with their id and DOM ref. This state is automatically updated when registerGroup and unregisterGroup are called.

Type
Group[]

hide RequiredRequired

Changes the visible state to false

Type
() => void

items RequiredRequired

Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.

Type
Item[]

last RequiredRequired

Moves focus to the last item.

Type
() => void

loop RequiredRequired

On one-dimensional composites:

  • true loops from the last item to the first item and vice-versa.
  • horizontal loops only if orientation is horizontal or not set.
  • vertical loops only if orientation is vertical or not set.
  • If currentId is initially set to null, the composite element will be focused in between the last and first items.

On two-dimensional composites:

  • true loops from the last row/column item to the first item in the same row/column and vice-versa. If it's the last item in the last row, it moves to the first item in the first row and vice-versa.
  • horizontal loops only from the last row item to the first item in the same row.
  • vertical loops only from the last column item to the first item in the column row.
  • If currentId is initially set to null, vertical loop will have no effect as moving down from the last row or up from the first row will focus the composite element.
  • If wrap matches the value of loop, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.

Type
boolean | Orientation

modal RequiredRequired

Toggles Dialog's modal state.

  • Non-modal: preventBodyScroll doesn't work and focus is free.
  • Modal: preventBodyScroll is automatically enabled, focus is trapped within the dialog and the dialog is rendered within a Portal by default.

Type
boolean

move RequiredRequired

Moves focus to a given item ID.

Type
(id: string | null) => void

next RequiredRequired

Moves focus to the next item.

Type
(unstable_allTheWay?: boolean | undefined) => void

place RequiredRequired

Change the placement state.

Type
Dispatch<SetStateAction<Placement>>

placement RequiredRequired

Actual placement.

Type
Placement

previous RequiredRequired

Moves focus to the previous item.

Type
(unstable_allTheWay?: boolean | undefined) => void

registerGroup RequiredRequired

Registers a composite group.

Type
(group: Group) => void

registerItem RequiredRequired

Registers a composite item.

Type
(item: Item) => void

reset RequiredRequired

Resets to initial state.

Type
() => void

rtl RequiredRequired

Determines how next and previous functions will behave. If rtl is set to true, they will be inverted. This only affects the composite widget behavior. You still need to set dir="rtl" on HTML/CSS.

Type
boolean

setAnimated RequiredRequired

Sets animated.

Type
Dispatch<SetStateAction<number | boolean>>

setBaseId RequiredRequired

Sets baseId.

Type
Dispatch<SetStateAction<string>>

setCurrentId RequiredRequired

Sets currentId. This is different from composite.move as this only updates the currentId state without moving focus. When the composite widget gets focused by the user, the item referred by the currentId state will get focus.

Type
Dispatch<SetStateAction<string | null | undefined>>

setLoop RequiredRequired

Sets loop.

Type
Dispatch<SetStateAction<boolean | Orientation>>

setModal RequiredRequired

Sets modal.

Type
Dispatch<SetStateAction<boolean>>

setOrientation RequiredRequired

Sets orientation.

Type
Dispatch<SetStateAction<Orientation | undefined>>

setRTL RequiredRequired

Sets rtl.

Type
Dispatch<SetStateAction<boolean>>

setShift RequiredRequired

Sets shift.

Type
Dispatch<SetStateAction<boolean>>

setVisible RequiredRequired

Sets visible.

Type
Dispatch<SetStateAction<boolean>>

setWrap RequiredRequired

Sets wrap.

Type
Dispatch<SetStateAction<boolean | Orientation>>

shift RequiredRequired

Has effect only on two-dimensional composites. If enabled, moving up or down when there's no next item or the next item is disabled will shift to the item right before it.

Type
boolean

show RequiredRequired

Changes the visible state to true

Type
() => void

sort RequiredRequired

Sorts the composite.items based on the items position in the DOM. This is especially useful after modifying the composite items order in the DOM. Most of the time, though, you don't need to manually call this function as the re-ordering happens automatically.

Type
() => void

stopAnimation RequiredRequired

Stops animation. It's called automatically if there's a CSS transition.

Type
() => void

toggle RequiredRequired

Toggles the visible state

Type
() => void

unregisterGroup RequiredRequired

Unregisters a composite group.

Type
(id: string) => void

unregisterItem RequiredRequired

Unregisters a composite item.

Type
(id: string) => void

unstable_arrowRef RequiredRequired

The arrow element.

Type
RefObject<HTMLElement | null>

unstable_arrowStyles RequiredRequired

Arrow styles.

Type
CSSProperties

unstable_disclosureRef RequiredRequired

Type
MutableRefObject<HTMLElement | null>

unstable_hasActiveWidget RequiredRequired

Type
boolean

unstable_idCountRef RequiredRequired

Type
MutableRefObject<number>

unstable_includesBaseElement RequiredRequired

Type
boolean

unstable_moves RequiredRequired

Stores the number of moves that have been performed by calling move, next, previous, up, down, first or last.

Type
number
Default
0

unstable_originalPlacement RequiredRequired

placement passed to the hook.

Type
Placement

unstable_popoverRef RequiredRequired

The popover element.

Type
RefObject<HTMLElement | null>

unstable_popoverStyles RequiredRequired

Popover styles.

Type
CSSProperties

unstable_referenceRef RequiredRequired

The reference element.

Type
RefObject<HTMLElement | null>

unstable_setHasActiveWidget RequiredRequired

Sets hasActiveWidget.

Type
Dispatch<SetStateAction<boolean>>

unstable_setIncludesBaseElement RequiredRequired

Sets includesBaseElement.

Type
Dispatch<SetStateAction<boolean>>

unstable_setValue RequiredRequired

Updates checkboxes and radios values within the menu.

Type
(name: string, value?: any) => void

unstable_setVirtual RequiredRequired

Sets virtual.

Type
Dispatch<SetStateAction<boolean>>

unstable_update RequiredRequired

Type
() => boolean

unstable_values RequiredRequired

Stores the values of radios and checkboxes within the menu.

Type
Record<string, any>

unstable_virtual RequiredRequired

If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite while its items receive virtual focus.

Type
boolean

up RequiredRequired

Moves focus to the item above.

Type
(unstable_allTheWay?: boolean | undefined) => void

visible RequiredRequired

Whether it's visible or not.

Type
boolean

wrap RequiredRequired

Has effect only on two-dimensional composites. 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.

  • true wraps between rows and columns.
  • horizontal wraps only between rows.
  • vertical wraps only between columns.
  • If loop matches the value of wrap, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.

Type
boolean | Orientation

MenuButton page anchor

baseId RequiredRequired

ID that will serve as a base for all the items IDs.

Type
string

first RequiredRequired

Moves focus to the first item.

Type
() => void

last RequiredRequired

Moves focus to the last item.

Type
() => void

placement RequiredRequired

Actual placement.

Type
Placement

show RequiredRequired

Changes the visible state to true

Type
() => void

toggle RequiredRequired

Toggles the visible state

Type
() => void

variant RequiredRequired

Type
| "reset" | "link" | "primary" | "primary_icon" | "secondary" | "secondary_icon" | "destructive" | "destructive_icon" | "destructive_link" | "destructive_secondary" | "inverse_link" | "inverse"
Default
'primary'

as

The HTML tag to replace the default <button> tag.

Type
keyof IntrinsicElements
Default
'button'

element

Overrides the default element name to apply unique styles with the Customization Provider.

Type
string
Default
'BUTTON'

fullWidth

Sets the Button width to 100% of the parent container.

Type
boolean

href

A URL to route to. Must use as="a" for this prop to work.

Type
string
Default
null

i18nExternalLinkLabel

Title for showExternal icon

Type
string
Default
'(link takes you to an external page)'

loading

Prevent actions and show a loading spinner

Type
boolean

pressed

Sets the aria-pressed attribute. Must be used with 'secondary' or 'secondary_icon' variants.

Type
boolean

size

Type
ButtonSizes
Default
'default'

target

Type
string

MenuBadge page anchor

baseId RequiredRequired

ID that will serve as a base for all the items IDs.

Type
string

first RequiredRequired

Moves focus to the first item.

Type
() => void

i18nButtonLabel RequiredRequired

Accessible label for the button that opens the menu

Type
string

last RequiredRequired

Moves focus to the last item.

Type
() => void

placement RequiredRequired

Actual placement.

Type
Placement

show RequiredRequired

Changes the visible state to true

Type
() => void

toggle RequiredRequired

Toggles the visible state

Type
() => void

variant RequiredRequired

Type
| "default" | "neutral" | "warning" | "error" | "success" | "new" | "subaccount" | "decorative10" | "decorative20" | "decorative30" | "decorative40" | "neutral_counter" | "error_counter" | "info"
Default
null

as

The HTML tag to replace the default <button> tag.

Type
keyof IntrinsicElements
Default
'button'

element

Overrides the default element name to apply unique styles with the Customization Provider.

Type
string
Default
'BUTTON'

fullWidth

Sets the Button width to 100% of the parent container.

Type
boolean

href

A URL to route to. Must use as="a" for this prop to work.

Type
string
Default
null

i18nExternalLinkLabel

Title for showExternal icon

Type
string
Default
'(link takes you to an external page)'

loading

Prevent actions and show a loading spinner

Type
boolean

pressed

Sets the aria-pressed attribute. Must be used with 'secondary' or 'secondary_icon' variants.

Type
boolean

size

Type
ButtonSizes
Default
'default'

target

Type
string

SubMenuButton page anchor

baseId RequiredRequired

ID that will serve as a base for all the items IDs.

Type
string

first RequiredRequired

Moves focus to the first item.

Type
() => void

last RequiredRequired

Moves focus to the last item.

Type
() => void

placement RequiredRequired

Actual placement.

Type
Placement

show RequiredRequired

Changes the visible state to true

Type
() => void

toggle RequiredRequired

Toggles the visible state

Type
() => void

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
'"SUBMENU_BUTTON"

MenuItem page anchor

down RequiredRequired

Moves focus to the item below.

Type
(unstable_allTheWay?: boolean | undefined) => void

first RequiredRequired

Moves focus to the first item.

Type
() => void

items RequiredRequired

Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.

Type
Item[]

last RequiredRequired

Moves focus to the last item.

Type
() => void

move RequiredRequired

Moves focus to a given item ID.

Type
(id: string | null) => void

next RequiredRequired

Moves focus to the next item.

Type
(unstable_allTheWay?: boolean | undefined) => void

previous RequiredRequired

Moves focus to the previous item.

Type
(unstable_allTheWay?: boolean | undefined) => void

registerItem RequiredRequired

Registers a composite item.

Type
(item: Item) => void

setCurrentId RequiredRequired

Sets currentId. This is different from composite.move as this only updates the currentId state without moving focus. When the composite widget gets focused by the user, the item referred by the currentId state will get focus.

Type
Dispatch<SetStateAction<string | null | undefined>>

unregisterItem RequiredRequired

Unregisters a composite item.

Type
(id: string) => void

up RequiredRequired

Moves focus to the item above.

Type
(unstable_allTheWay?: boolean | undefined) => void

as

Type
any

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
'MENU_ITEM'

href

Pass href prop to render an anchor element.

Type
string

variant

Type
MenuItemVariant

MenuItemCheckbox page anchor

down RequiredRequired

Moves focus to the item below.

Type
(unstable_allTheWay?: boolean | undefined) => void

first RequiredRequired

Moves focus to the first item.

Type
() => void

items RequiredRequired

Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.

Type
Item[]

last RequiredRequired

Moves focus to the last item.

Type
() => void

move RequiredRequired

Moves focus to a given item ID.

Type
(id: string | null) => void

name RequiredRequired

MenuItemCheckbox's name as in menu.values.

Type
string

next RequiredRequired

Moves focus to the next item.

Type
(unstable_allTheWay?: boolean | undefined) => void

previous RequiredRequired

Moves focus to the previous item.

Type
(unstable_allTheWay?: boolean | undefined) => void

registerItem RequiredRequired

Registers a composite item.

Type
(item: Item) => void

setCurrentId RequiredRequired

Sets currentId. This is different from composite.move as this only updates the currentId state without moving focus. When the composite widget gets focused by the user, the item referred by the currentId state will get focus.

Type
Dispatch<SetStateAction<string | null | undefined>>

unregisterItem RequiredRequired

Unregisters a composite item.

Type
(id: string) => void

unstable_setValue RequiredRequired

Updates checkboxes and radios values within the menu.

Type
(name: string, value?: any) => void

unstable_values RequiredRequired

Stores the values of radios and checkboxes within the menu.

Type
Record<string, any>

up RequiredRequired

Moves focus to the item above.

Type
(unstable_allTheWay?: boolean | undefined) => void

as

Type
any

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
MENU_ITEM_CHECKBOX

href

Pass href prop to render an anchor element.

Type
string

variant

Type
MenuItemVariant

MenuItemRadio page anchor

down RequiredRequired

Moves focus to the item below.

Type
(unstable_allTheWay?: boolean | undefined) => void

first RequiredRequired

Moves focus to the first item.

Type
() => void

items RequiredRequired

Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.

Type
Item[]

last RequiredRequired

Moves focus to the last item.

Type
() => void

move RequiredRequired

Moves focus to a given item ID.

Type
(id: string | null) => void

name RequiredRequired

MenuItemRadio's name as in menu.values.

Type
string

next RequiredRequired

Moves focus to the next item.

Type
(unstable_allTheWay?: boolean | undefined) => void

previous RequiredRequired

Moves focus to the previous item.

Type
(unstable_allTheWay?: boolean | undefined) => void

registerItem RequiredRequired

Registers a composite item.

Type
(item: Item) => void

setCurrentId RequiredRequired

Sets currentId. This is different from composite.move as this only updates the currentId state without moving focus. When the composite widget gets focused by the user, the item referred by the currentId state will get focus.

Type
Dispatch<SetStateAction<string | null | undefined>>

unregisterItem RequiredRequired

Unregisters a composite item.

Type
(id: string) => void

unstable_setValue RequiredRequired

Updates checkboxes and radios values within the menu.

Type
(name: string, value?: any) => void

unstable_values RequiredRequired

Stores the values of radios and checkboxes within the menu.

Type
Record<string, any>

up RequiredRequired

Moves focus to the item above.

Type
(unstable_allTheWay?: boolean | undefined) => void

value RequiredRequired

Same as the value attribute.

Type
| string | number | (string & readonly string[]) | (number & readonly string[])

as

Type
any

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
MENU_ITEM_CHECKBOX

href

Pass href prop to render an anchor element.

Type
string

variant

Type
MenuItemVariant

MenuGroup page anchor

label RequiredRequired

Accessible name of the MenuGroup.

Type
string

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
MENU_GROUP

icon

Pass a decorative Paste icon to display with the group label.

Type
| string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | ReactFragment | ReactPortal

MenuSeparator page anchor

element

Type
string

Menu page anchor

aria-label RequiredRequired

Defines a string value that labels the current element.

Type
string

baseId RequiredRequired

ID that will serve as a base for all the items IDs.

Type
string

first RequiredRequired

Moves focus to the first item.

Type
() => void

items RequiredRequired

Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.

Type
Item[]

last RequiredRequired

Moves focus to the last item.

Type
() => void

move RequiredRequired

Moves focus to a given item ID.

Type
(id: string | null) => void

next RequiredRequired

Moves focus to the next item.

Type
(unstable_allTheWay?: boolean | undefined) => void

placement RequiredRequired

Actual placement.

Type
Placement

previous RequiredRequired

Moves focus to the previous item.

Type
(unstable_allTheWay?: boolean | undefined) => void

setCurrentId RequiredRequired

Sets currentId. This is different from composite.move as this only updates the currentId state without moving focus. When the composite widget gets focused by the user, the item referred by the currentId state will get focus.

Type
Dispatch<SetStateAction<string | null | undefined>>

element

Type
string