An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:DropdownMenuItem authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-31 owners: [cixzhang] review_triggers: [public-api, behavior, accessibility, theming, testing] verified_by: [ packages/core/src/DropdownMenu/DropdownMenu.test.tsx, packages/core/src/DropdownMenu/tests/Menu.a11y.test.tsx, packages/core/src/theme/themingTargets.test.ts, apps/storybook/rtl-audit/verified-not-applicable.json, scripts/check-knowledge.mjs, ] modules: [] families: [family:navigation-destinations] design_specs: [] architecture: [ architecture:public-component-api, architecture:component-theming-surface, architecture:component-test-sufficiency, architecture:interaction-modality, ] contributing: []
system_specs: [spec:AST-020]
DropdownMenuItem component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | One compound pointer-menu row for an action or destination, with label, supporting content, disabled state, destructive paint, optional close suppression, root inputs, and a forwarded ref. |
| Behavior | The parent menu owns roving focus and keyboard activation; the row owns click order, disabled suppression, close-on-select, destination handoff, hover focus, and its visible content composition. |
| End-user impact | Actions and destinations preserve keyboard, pointer, and browser link behavior while unavailable rows remain inert and destructive actions remain identifiable. |
| Builder impact | Destinations use href; supporting content stays non-interactive; hasCloseOnSelect=false is reserved for in-place result feedback. |
| Compatibility/readiness | Records shipped behavior; no API change; a disabled row gains tabindex="-1" (FR7). |
| Review checks | Reject nested controls, disabled activation, lost destination safety, broken modified-click behavior, dropped root inputs, a second keyboard owner, or state/target reflection moved off the row. |
| Governing rules | family:navigation-destinations/FR1–FR5; architecture:public-component-api/INV5–INV9; architecture:component-theming-surface/INV3–INV6; spec:AST-020/FR1,FR2,FR6,FR15. |
This table is a review projection; the body below is authoritative.
Intent
DropdownMenuItem renders one compound-mode row in the pointer presentation of
DropdownMenu. It owns the row element, content slots, action-versus-destination
branch, activation order, disabled and destructive state, root composition, and
dropdown-menu-item theme target. DropdownMenu owns the surrounding menu,
keyboard collection, focus movement, typeahead, presentation choice, and close
lifecycle.
Compatibility and migration
- Released default preserved: yes.
- Compatibility class: records shipped behavior; no public prop or export
change; a disabled row gains
tabindex="-1"(FR7). - Controlled/uncontrolled behavior: not applicable.
- Migration decision: none.
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- One
role="menuitem"root and its label, description, icon, end content, disabled state, destructive variant, ref, supported host inputs, and styling inputs. - Action callback order and
hasCloseOnSelectbehavior. - Link-row rendering, destination handoff, modified/middle-click preservation, target and relationship handling, and disabled-link inertness.
- Pointer hover focus and the row's press/hover/focus paint.
- The
dropdown-menu-itemtarget and its size/variant state reflection.
Does not own / non-goals
- Menu naming, open/close state, focus entry, roving focus, typeahead, and keyboard click synthesis — owned by DropdownMenu and its shared hooks.
- Touch and bottom-sheet row rendering — the parent presentation delegates those rows to List.
- Destination acceptance and blocking — owned by
family:navigation-destinations. - Interactive controls inside label, description, or end content. Controls belong beside the menu or as separate rows.
Public concepts
| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Row act | action; destination | Runs a callback or exposes a browser/router destination from the row itself. | Every enabled row | action | component and navigation family | stable | A blocked destination is inert; a disabled link has no href. |
| Availability | enabled; disabled | Controls whether the row can activate; a disabled row still takes keyboard focus (FR7). | Every row | enabled | component and parent menu | stable | Disabled suppresses activation and destination, not keyboard focus. |
| Close policy | close; remain open | Whether successful activation closes the parent menu. | Action and destination rows | close | component | stable | Omission closes. |
| Visual state | default; destructive; hover; focus; press; disabled | Paints row meaning and interaction state without changing menuitem semantics. | Pointer row | default | component | stable | Unknown variants are rejected by the public type. |
| Root surface | ref; DOM/data/ARIA; class/style/xstyle/events | Extends the row root while preserving component-owned role and keyboard state. | Every pointer row | omitted | public component API | stable | Accepted inputs compose; owned role/tab stop remain fixed. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | The pointer row exposes one role="menuitem" root. Label, description, icon, and end content are presentational content of that row rather than nested controls. |
spec:AST-020 FR15; current source and docs |
| FR2 | Enabled activation runs the row callback before optional close. Disabled rows expose aria-disabled=true, remove link destinations, and run neither callback nor close. |
Current behavior and tests |
| FR3 | A destination row renders as the link root through LinkProvider. Plain activation runs the callback then closes and navigates; a modified click does not run the callback, closes the menu, and is left to the browser; a middle click closes the menu (hasCloseOnSelect), then runs the caller's onAuxClick; blocked schemes are inert. |
family:navigation-destinations FR1–FR5; current tests |
| FR4 | The parent menu is the only keyboard owner. It synthesizes click activation with modifiers, moves focus, and runs typeahead; the row focuses itself on mouse hover and creates no second roving-focus model. | architecture:interaction-modality; current parent tests |
| FR5 | The visible root carries dropdown-menu-item; size and destructive state reflect on it (data-size, data-variant); semantic tokens own layout and paint before caller styling inputs compose. |
architecture:component-theming-surface; current source and tests |
| FR6 | Ref, supported host attributes and handlers, className, style, and xstyle reach or compose on the row root without replacing owned role, tab stop, disabled behavior, destination handling, or activation order. |
architecture:public-component-api INV5–INV9; current tests |
| FR7 | Disabled menu rows remain inert, and the parent menu's keyboard reaches them as component:DropdownMenu FR17 states. |
component:DropdownMenu FR17, DEC-11 |
| FR8 | Keyboard focus draws the shared focus ring inside the row, inset by the ring's own width, in every color mode; forced colors keep that ring as the focus indicator. After pointer input the row shows only its hover background (architecture:interaction-modality INV1), or the pressed overlay while a held finger or pen lights it (spec:AST-094 FR27); the focused row owns the indicator (INV3). |
Current source; architecture:interaction-modality INV1, INV3 |
Allowed variation
- AV1 — Content. Non-interactive icons, text, descriptions, shortcuts, badges, and status text may vary without changing the row's menuitem semantics.
- AV2 — Theme paint. A theme may restyle the target's admitted properties while preserving visible state distinctions and forced-colors focus.
- AV3 — Parent size. The parent menu supplies
sm,md, orlg; the row reflects that state and may vary its tokenized insets.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Enabled action | Callback runs, then close follows the close policy. | Content, size, and visual variant. |
| In-place result action | Callback runs and the menu remains open. | Label/end content may update. |
| Disabled action | aria-disabled=true; callback, hover focus, and close are suppressed. |
Content remains visible. |
| Destination | One anchor root preserves safe destination and browser activation behavior. | Target, rel, router provider, and content. |
| Destructive | Error-role paint applies to label, icon, and description without changing behavior. | Other row content remains consumer-authored. |
| Keyboard focus | Parent focus lands on the row and remains visible. | Exact theme-owned paint may vary. |
| RTL / narrow viewport | Logical insets and start alignment follow direction without horizontal overflow. | Menu placement remains parent-owned. |
Transformation and precedence order
- ORD1 — Activation. Disabled guard → browser-navigation classification → row callback where applicable → close policy → browser/router navigation.
- ORD2 — Root composition. Parent size → base row styles → variant/disabled state
→ caller
xstyle; target metadata and caller class/style compose on the same root.
Performance and resources
- PR1 — Shared press listeners. The row shares the press controller's window and document listeners; it adds no per-row listener, observer, timer, or request.
Accessibility contract
- AR1 — Menu item semantics. The root is one named
menuitem; supporting content does not introduce a nested interactive descendant. - AR2 — Disabled state. Disabled rows expose state and cannot activate or navigate.
- AR3 — Keyboard ownership. DropdownMenu owns focus collection and activation; the item remains a single row in that model.
- AR4 — Focus perception. After keyboard input the focused row draws the shared focus ring inside its edge in every color mode, forced colors included; after pointer input its background follows FR8.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Row | One full-width action/destination target with tokenized insets and start alignment. | Current source and parent menu composition | prominent | FR1–FR6 |
| Supporting text | Description and end content remain subordinate to the row label. | Delegated Item layout and current consumer docs | supporting | FR1 |
| Interaction | Hover, focus, press, disabled, and destructive states remain distinguishable. | Current source; FR8 | prominent | FR5, FR8, AR4 |
No component-local visual decision is recorded.
Family and system relationships
family:navigation-destinationsowns destination acceptance and blocked-scheme behavior; this component supplies the destination-bearing row.architecture:public-component-apiowns root input composition, refs, and released compatibility.architecture:component-theming-surfaceowns target placement and state reflection.architecture:component-test-sufficiencyowns proportionate observable evidence.architecture:interaction-modalityand DropdownMenu own parent keyboard behavior.spec:AST-020supplies WCAG/APG adoption and evidence-layer boundaries.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR1 | DropdownMenu.test.tsx compound-mode cases ("renders JSX children as menu items", "renders endContent after the item label"); Menu.a11y.test.tsx menu binding cases |
Action row with content | A row that is not a menuitem or loses its content fails. Evidence gap: no test asserts that supporting content holds no nested control. |
audit:DropdownMenuItem/semantics |
| FR2, AR2, ORD1 | DropdownMenu.test.tsx item cases ("calls onClick when item is clicked", "closes the menu after an item is activated", "keeps the menu open when the item opts out of closing", "does not call onClick when disabled"), "has aria-disabled on disabled compound items", and "a disabled href row renders no address" |
Enabled, disabled, close and stay-open | A callback while disabled, a missing aria-disabled, a close that ignores the policy, or a disabled row with an address fails. Evidence gap: no test asserts the callback-before-close order. |
audit:DropdownMenuItem/behavior |
| FR3 | DropdownMenu.test.tsx "DropdownMenuItem href" and "link rows — the browser's own clicks" cases; "a middle click on a link row runs the caller's onAuxClick and still closes the menu" |
Plain, modified, middle, right click; blocked destination | A non-anchor row, a modified click that runs the callback, a middle click that does not close, or a live blocked destination fails. | audit:DropdownMenuItem/behavior |
| FR4, AR3 | DropdownMenu.test.tsx keyboard-access cases ("moves focus to the item the mouse hovers, keeping a single highlight", "does not move focus on hover for a disabled item", "does not move focus for a non-mouse (touch) pointer") and "keeps the row's own role, tab stop and hover focus beside a caller's onPointerMove" |
Mouse hover, touch, disabled | A second highlight, hover focus on a disabled row or under touch, or a lost tab stop fails. | audit:DropdownMenuItem/accessibility |
| FR5 | DropdownMenu.test.tsx destructive-variant cases; themingTargets.test.ts |
Default and destructive; data and compound mode | A missing data-variant fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts the dropdown-menu-item class or data-size. |
audit:DropdownMenuItem/theming |
| FR6 | DropdownMenu.test.tsx ref and host-attribute cases ("a ref reaches the menuitem element", "puts aria-*, data-* and id on the row root, a link row included", "runs the DOM handlers the caller attaches, such as a drop target") |
Ref; host attributes; caller handlers | A dropped ref, attribute, or handler fails. Evidence gap: no test asserts className, style, or xstyle on the row. |
audit:DropdownMenuItem/api |
| FR7 | DropdownMenu.test.tsx disabled-row keyboard cases (component:DropdownMenu FR17) |
Disabled rows | A disabled row that activates, closes the menu, or is skipped by the parent's arrow keys or type-ahead fails. | audit:DropdownMenuItem/accessibility |
| FR8, AR4, PR1 | DropdownMenuForcedColors.test.tsx (each row's :focus-visible ring and token inset); DropdownMenuAudit.a11y.chromium.spec.ts forced-colors frames |
Action and destructive rows; light, dark, forced colors | A row without the ring after keyboard input, or a ring not inset by the ring width, fails. Evidence gap: no test asserts the listener bound. | audit:DropdownMenuItem/visual |
| RTL | apps/storybook/rtl-audit/verified-not-applicable.json DropdownMenuItem entry |
LTR and RTL | A changed source hash fails the receipt. | audit:DropdownMenuItem/rtl |
Current-state impact
None.
Decision log
No component-local decision.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit scores, screenshot matrices, implementation steps, or family/system rules. It links to their owners.