Skip to main content
Design system

Action Menu

A temporary overlay containing a list of items (commands or actions) relevant to the user’s current context. An item in the menu is immediately executed upon selection. Action menus must be paired with a trigger (button or text link) that reveals the menu on click or tap.

Bundle size: 203.01 kB
Install:
npm install @washingtonpost/wpds-ui-kit
|Copy
Usage:
import { ActionMenu } from "@washingtonpost/wpds-ui-kit"
|Copy
Storybook:  View on Storybook
Source:  View on Github

Anatomy

Note: Image not to scale

  1. Trigger
  2. Item label
  3. Submenu indicator
  4. Group label
  5. Group divider
  6. Item icon (optional)
  7. Selected item
  8. Unselected item

Options

Density

The following options can be applied to specify the density of the items: default, loose, and compact.

Trigger

The Action List can be triggered with a button, a link, an icon, or similar visual cue.


Behavior

Disabled

A menu item can be set to ‘disabled’, according to the user’s current context and relevance of option(s).

Hover

Items display background color ‘$faint’ on mouse over

Select

Action menu items can be made selectable using radio (I.E. only one option permitted) or multi-select functionality. Menu items are selected or deselected via user input. Selected items are visually indicated in bold along with the ([glyph: check]) icon.

The submenu indicator, ([glyph: chevron-right]) is used to identify items containing a submenu. Action menu supports up to three layers of submenu — level 1 (i.e., root), level 2 and level 3. To access a submenu, hover over the menu item or use keyboard navigation. Each menu level has a specific elevation in the stacking order, corresponding to its place in the nesting hierarchy. Additionally, menu containers for levels 1, 2 and 3 possess individual shadow depths, corresponding to shadow tokens ‘$300, ‘$400’, and ‘$500’, respectively.


Guidance

It’s recommended to limit the number of items to no more than five (5) options in a given menu list. Reducing the number of options avoids overwhelming the user and aides in making an accurate selection. If your action menu requires more options, consider using group labels to provide additional visual clarity.

In general, it’s best to place the most frequently used or encouraged options towards the top of the menu list, for easier scannability.

Accessibility

Keyboard controls

KeyDescription
SpaceWhen focus is on DropdownMenu.Trigger, opens the dropdown menu and focuses the first item. When focus is on an item, activates the focused item.
EnterWhen focus is on DropdownMenu.Trigger, opens the dropdown menu and focuses the first item. When focus is on an item, activates the focused item.
ArrowDownWhen focus is on DropdownMenu.Trigger, opens the dropdown menu. When focus is on an item, moves focus to the next item.
ArrowUpWhen focus is on an item, moves focus to the previous item.
ArrowRight, ArrowLeftWhen focus is on DropdownMenu.SubTrigger, opens or closes the submenu depending on reading direction.
EscCloses the dropdown menu and moves focus to DropdownMenu.Trigger.

API Reference

ActionMenuCheckboxItem

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
onSelect
(event: Event) => void
----False
asChild
boolean
----False
disabled
boolean
----False
textValue
string
----False
checked
CheckedState
----False
onCheckedChange
(checked: boolean) => void
----False

ActionMenuContent

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
asChild
boolean
----False
side
"left" | "right" | "bottom" | "top"
----False
sideOffset
number
----False
align
"center" | "end" | "start"
----False
alignOffset
number
----False
arrowPadding
number
----False
collisionBoundary
Element | Element[]
----False
collisionPadding
number | Partial<Record<"left" | "right" | "bottom" | "top", number>>
----False
sticky
"always" | "partial"
----False
hideWhenDetached
boolean
----False
avoidCollisions
boolean
----False
onCloseAutoFocusEvent handler called when auto-focusing on close. Can be prevented.
(event: Event) => void
----False
loopWhether keyboard navigation should loop around @defaultValue false
boolean
----False
onEscapeKeyDown
(event: KeyboardEvent) => void
----False
onPointerDownOutside
(event: PointerDownOutsideEvent) => void
----False
onFocusOutside
(event: FocusOutsideEvent) => void
----False
onInteractOutside
(event: PointerDownOutsideEvent | FocusOutsideEvent) => void
----False
forceMountUsed to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
true
----False

ActionMenuGroup

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
asChild
boolean
----False

ActionMenuIcon

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
side
"left" | "right"
left False

ActionMenuItem

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
onSelect
(event: Event) => void
----False
asChild
boolean
----False
disabled
boolean
----False
textValue
string
----False

ActionMenuItemIndicator

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
asChild
boolean
----False
forceMountUsed to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
true
----False

ActionMenuLabel

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
asChild
boolean
----False

ActionMenuPortal

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
forceMountUsed to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
true
----False
container
HTMLElement
----False

ActionMenuRadioGroup

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
asChild
boolean
----False
value
string
----False
onValueChange
(value: string) => void
----False

ActionMenuRadioItem

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
onSelect
(event: Event) => void
----False
asChild
boolean
----False
disabled
boolean
----False
textValue
string
----False
value
string
----
True

ActionMenuRoot

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
density
DensityProp
default False
dir
Direction
----False
open
boolean
----False
defaultOpen
boolean
----False
onOpenChange
(open: boolean) => void
----False
modal
boolean
----False

ActionMenuSeparator

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
asChild
boolean
----False

ActionMenuSub

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
open
boolean
----False
defaultOpen
boolean
----False
onOpenChange
(open: boolean) => void
----False

ActionMenuSubContent

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
shadowSize
ShadowProp
----False
asChild
boolean
----False
sideOffset
number
----False
alignOffset
number
----False
arrowPadding
number
----False
collisionBoundary
Element | Element[]
----False
collisionPadding
number | Partial<Record<"left" | "right" | "bottom" | "top", number>>
----False
sticky
"always" | "partial"
----False
hideWhenDetached
boolean
----False
avoidCollisions
boolean
----False
loopWhether keyboard navigation should loop around @defaultValue false
boolean
----False
onEscapeKeyDown
(event: KeyboardEvent) => void
----False
onPointerDownOutside
(event: PointerDownOutsideEvent) => void
----False
onFocusOutside
(event: FocusOutsideEvent) => void
----False
onInteractOutside
(event: PointerDownOutsideEvent | FocusOutsideEvent) => void
----False
forceMountUsed to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
true
----False

ActionMenuSubTrigger

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
onClick
(() => void) & MouseEventHandler<HTMLDivElement>
----False
asChild
boolean
----False
disabled
boolean
----False
textValue
string
----False

ActionMenuTrigger

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
asChild
boolean
----False
Edit this page on GitHub.