Cloaked Design SystemControls

Prop	Type	Presence	Notes
`items`	`MenuItem[]`	Required	Rows in render order. Keep one meaning per menu: all commands, or all option values.
`ariaLabel`	`string`	Required	Accessible name for the container; the trigger's label sits on a separate element.
`selectionMode`	`MenuSelectionMode \| undefined`	Optional	Selection semantics. Use `single` for picker-style menus.Source default: `'none'`
`value`	`string \| undefined`	Optional	Current selected value when `selectionMode` is `single`.
`onSelect`	`((value: string) => void) \| undefined`	Optional	Called with the pressed row's `value`. Omitting it makes every row inert.
`haptic`	`HapticFeedback \| undefined`	Optional	Haptic feedback for item presses. Defaults to `true` (`selection` for single-select, otherwise `light`).Source default: `true`
`className`	`string \| undefined`	Optional
`style`	`React.CSSProperties \| undefined`	Optional
`testId`	`string \| undefined`	Optional	Container selector, and the stem each row's selector is derived from.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

The option-list body for bottom sheets, popovers, and dropdown content — the rows, not the trigger. selectionMode switches its meaning: single is a picker, none is an action list.

When to use

Reach for Menu whenever you need a list of rows inside an opened surface. Two modes:

selectionMode="single" renders a picker (role listbox/option, a check on the current value) — the body of a Select or Dropdown sheet.
selectionMode="none" renders an action list (role menu/menuitem) of one-off commands like Rename, Share, Delete. Items can be disabled or destructive.

Choosing between the neighbors:

Need the collapsed trigger that opens this list? That's Dropdown (or Select for a form value).
Picking one value from a short fixed set inside a form? Use Select, which composes a Menu internally.
Filtering a long list by typing? Use Autocomplete.

In-app it renders the activity-filter rows opened from the Dropdown in ActivityFeed.tsx.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: container
Label: Container
Description: Owns the menu or listbox role, accessible name, and row spacing.

Id: item
Label: Item
Description: Native button exposing action or option semantics and disabled state.

Id: leading
Label: Leading visual
Description: Optional icon or visual before item copy.

Id: label
Label: Item label
Description: Primary action or option name.

Id: description
Label: Item description
Description: Optional supporting copy beneath an action label.

Id: selection-mark
Label: Selection mark
Description: Trailing check shown only on the selected single-choice item.

Allowed Design Choices

Variants

Base

Label: Base
Description: One row treatment configured through the independent selection-mode axis.

Sizes

Selection Modes

None

Label: Actions
Description: Exposes menu and menuitem semantics for one-off commands.

Single

Label: Single selection
Description: Exposes listbox and option semantics with one selected value.

Variants

Id: base
Label: Base
Description: Compact menu rows whose role is selected through a separate semantic mode.
Platforms: ios
android
web

Sizes

None specified

Measurements

Id: container-gap
Label: Item gap
Kind: exact
Token: --cds-space-4
Value: 4
Unit: px
Applies To: container
item

Id: item-min-height
Label: Item minimum height
Kind: exact
Token: --cds-size-48
Value: 48
Unit: px
Applies To: item

Id: item-horizontal-padding
Label: Item horizontal padding
Kind: exact
Token: --cds-space-16
Value: 16
Unit: px
Applies To: item

Id: item-corner-radius
Label: Item corner radius
Kind: exact
Token: --cds-radius-md
Value: 16
Unit: px
Applies To: item

Layout

Alignment: Leading visual and copy align at the row start while the selected check remains trailing.
Flow: Rows stack vertically; each row contains optional leading visual, flexible copy, then optional selection mark.
Notes: Use action mode for commands and single-selection mode for values; do not mix both meanings in one menu.
Place Menu inside an owned surface such as Modal or popover.

Typography And Color

Typography

Label: Item label
Description: Use the body ramp for primary row labels.
Token: --cds-type-body-size

Label: Description
Description: Use body-small for supporting copy.
Token: --cds-type-body-small-size

Colors

Label: Selected row
Description: Fill the selected single-choice row with the bold surface so selection reads as a high-contrast pill, consistent with other selected controls.
Token: --cds-bg-bold

Label: Selected row content
Description: Flip the selected row's label and check to on-bold so they read on the bold fill.
Token: --cds-text-on-bold

Label: Primary label
Description: Use primary text emphasis for normal actions and unselected options.
Token: --cds-text-primary

Label: Description and leading visual
Description: Use secondary text emphasis.
Token: --cds-text-secondary

Label: Destructive action
Description: Use the solid danger role only for irreversible actions.
Token: --cds-status-danger-solid

Label: Selection mark
Description: Use on-bold for the selected check, which sits on the bold selected row.
Token: --cds-text-on-bold

States

Id: default
Label: Default
Description: Shows an enabled normal item.

Id: selected
Label: Selected
Description: Fills the row with the bold surface and shows an on-bold check and option state in single-selection mode.

Id: focused
Label: Focused
Description: Shows a visible focus ring on the row button.

Id: disabled
Label: Disabled
Description: Blocks the item and dims its full contents.

Id: destructive
Label: Destructive
Description: Uses danger emphasis for an enabled irreversible action.

Behavior

Label: Action mode
Description: Emit the pressed value from menu items without maintaining selected state.

Label: Single-selection mode
Description: Expose the controlled value as one selected option and emit a new value on press.

Label: Disabled items
Description: Never emit selection or action callbacks from disabled rows.

Accessibility

Label: Container semantics
Description: Require an accessible name and expose menu for actions or listbox for single selection.

Label: Row semantics
Description: Expose menuitem or option roles consistently with the container mode.

Label: Selection and disabled state
Description: Expose selected state only in single-selection mode and preserve native disabled behavior.

Content Adaptation

Label: Long copy
Description: Wrap labels and descriptions within the flexible copy column.

Label: Destructive labels
Description: Name the affected object and action clearly; danger color does not replace explicit wording.

Motion Haptics

Motion

Label: Selection change
Description: Update selected surface and check without changing row geometry.

Haptics

Label: Mode-aware feedback
Description: Request selection feedback for single-choice items and light feedback for action items.

Platform Differences

Platforms: web
Description: Web maps modes to ARIA menu/menuitem or listbox/option roles; native platforms map the same distinction to action and selectable-row accessibility traits.
Rationale: Semantic intent is shared while each platform exposes its native assistive-technology vocabulary.

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1

Playground

Overview

When to use

Component specification