An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:DropdownMenuCheckboxItem 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] verified_by: [ packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx, packages/core/src/DropdownMenu/DropdownMenu.test.tsx, ] modules: [] families: [] design_specs: [] architecture: [ architecture:public-component-api, architecture:component-theming-surface, architecture:interaction-modality, ] contributing: []
system_specs: [spec:AST-020]
DropdownMenuCheckboxItem component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | One pointer-menu row that toggles an independent boolean: label, description, icon, endContent, controlled value and onChange, isDisabled, hasCloseOnSelect (default false), root inputs, and a ref. |
| Behavior | The row is one menuitemcheckbox whose aria-checked is its value; an enabled activation reports !value and keeps the menu open unless asked to close; a disabled row is inert. |
| End-user impact | People toggle options without the menu closing on each change, and screen-reader users hear one checkbox per row. |
| Builder impact | Builders own the value; the row composes their click and pointer-move handlers with its own activation and hover focus. |
| Compatibility/readiness | Records shipped behavior; no API change; a disabled row gains tabindex="-1" (FR3). Enter keeping the menu open is listed under Current-state impact (OQ1). |
| Review checks | Reject a nested announced checkbox, a row that closes by default, a dropped caller handler, or an activation while disabled. |
| Governing rules | spec:AST-020 FR15; architecture:public-component-api INV5–INV8; architecture:interaction-modality. |
This table is a review projection; the body below is authoritative.
Intent
DropdownMenuCheckboxItem renders one compound-mode row that toggles an independent boolean inside the pointer presentation of DropdownMenu. DropdownMenu owns focus movement, typeahead, keyboard click synthesis, and the close lifecycle.
Compatibility and migration
- Released default preserved: yes (
hasCloseOnSelect=false). - Compatibility class: records shipped behavior; no public prop or export
change; a disabled row gains
tabindex="-1"(FR3). - Controlled/uncontrolled behavior: controlled;
valueis caller-owned. - Migration decision: none.
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- One
role="menuitemcheckbox"root, itsaria-checked, label, description, icon, end content, disabled state, ref, supported host inputs, and styling inputs. - Activation: reporting
!value, the close policy, and composing the caller's click and pointer-move handlers. - The decorative checkbox marker and the row's
dropdown-menu-itemtarget.
Does not own / non-goals
- Focus entry, roving focus, typeahead, and Enter/Space click synthesis — owned
by
component:DropdownMenu. - Checkbox chrome — delegated to
component:Indicator. - How the keyboard reaches a disabled row —
component:DropdownMenuFR17.
Public concepts
| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Checked state | true, false |
The boolean the row shows and toggles. | Every row | required | caller | stable | Required by the public type. |
| Close policy | close; remain open | Whether an enabled toggle closes the menu. | Every enabled row | remain open | component | stable | Omission keeps the menu open. |
| Availability | enabled; disabled | Whether the row can activate. | Every row | enabled | component | stable | Disabled blocks activation. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | The row renders one element with role="menuitemcheckbox" whose aria-checked equals value; the checkbox marker is decorative (aria-hidden), so the row is the only announced control. |
spec:AST-020 FR15; current source and tests |
| FR2 | An enabled activation, by pointer or by the parent's synthesized Enter/Space click, calls onChange(!value), then closes the menu when hasCloseOnSelect is set, then calls the caller's onClick; without hasCloseOnSelect the menu stays open. The APG Menu pattern's Enter closes the menu, and spec:AST-020 FR15 requires this record to name any required part it does not adopt. Implementation gap: Enter keeps the menu open by default, and no exception is named (OQ1). |
spec:AST-020 FR15; architecture:public-component-api INV7; current tests |
| FR3 | A disabled row exposes aria-disabled="true", carries tabindex="-1" like an enabled row so the parent's keyboard model reaches it (component:DropdownMenu FR17), and on any activation calls neither onChange nor the caller's activation handlers and does not close the menu. |
Current source and tests |
| FR4 | Ref, supported host attributes and handlers, className, style, and xstyle reach or compose on the row root; caller onPointerMove composes with the row's hover focus. |
architecture:public-component-api INV5–INV8; current tests |
| FR5 | The marker is the shared checkbox Indicator, sm in a small menu; the row carries the dropdown-menu-item target with the menu size. |
architecture:component-theming-surface; current source and tests |
| FR6 | The row adds no key handler or tab stop of its own: every row, disabled included, is tabindex="-1" for the parent's roving focus, and the parent's keyboard reaches a disabled row (component:DropdownMenu FR17). |
architecture:interaction-modality; parent tests |
Allowed variation
- AV1 — Content. Label, description, icon, and end content are caller content.
- AV2 — Theme paint. Themes may restyle the row and marker targets.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Unchecked | aria-checked="false"; marker empty. |
Content. |
| Checked | aria-checked="true"; marker checked. |
Content. |
| Close on select | An enabled toggle closes the menu. | — |
| Disabled | aria-disabled="true"; no activation. |
Content stays visible. |
Transformation and precedence order
- ORD1 — Activation. Disabled guard →
onChange(!value)→ close whenhasCloseOnSelect→ calleronClick.
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 — One checkbox control. The row owns
menuitemcheckbox, its accessible name, checked state, focus, and activation; the marker is decorative. - AR2 — Disabled state. A disabled row is inert.
- AR3 — Focus visibility. Keyboard focus draws the shared focus ring
inside the row, inset by the ring's own width, in every color mode, forced
colors included; after pointer input the row shows only the overlay tint
(
architecture:interaction-modalityINV1, INV3). The shared row treatment iscomponent:DropdownMenuItemFR8.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Row | One full-width toggle row. | Current source | Prominent | FR1, FR5 |
| Marker | Shows the checked state. | component:Indicator |
Supporting | FR1, FR5 |
The shared DropdownMenu.doc.mjs anatomy and component:DropdownMenu theming
anatomy map the row and checkbox indicator, so this record carries no
anatomy-theming map.
Family and system relationships
component:DropdownMenuowns the keyboard model and close lifecycle.component:Indicatorowns the checkbox chrome.architecture:public-component-apiowns root composition and handler order.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR1 | DropdownMenuSelectable.test.tsx "keeps the checkbox indicator decorative (row is the only announced control)"; "a ref reaches the menuitemcheckbox element" |
Checked and unchecked | An announced marker or a row that is not menuitemcheckbox fails. |
audit:DropdownMenuCheckboxItem/semantics |
| FR2, ORD1 | DropdownMenuSelectable.test.tsx "calls onChange with the toggled value on click", "composes the caller click handler with the checked-state change", "composes the caller click handler on keyboard activation", "closes after a successful toggle only when requested"; DropdownMenu.test.tsx "activates a focused menuitemradio with Enter and a menuitemcheckbox with Space" |
Pointer and keyboard; close on and off | A wrong value, a dropped caller onClick, or a close without the opt-in fails. Evidence gap: no test asserts the onChange, close, onClick order. |
audit:DropdownMenuCheckboxItem/behavior |
| FR3, AR2 | DropdownMenuSelectable.test.tsx "does not call consumer activation handlers when disabled" and "does not toggle when disabled" |
Disabled | A toggle, a close, or a caller handler while disabled fails. Evidence gap: no test asserts the disabled row's tabindex="-1". |
audit:DropdownMenuCheckboxItem/behavior |
| FR4 | DropdownMenuSelectable.test.tsx "composes the caller pointer-move handler with menu hover focus" and "a ref reaches the menuitemcheckbox element" |
Ref; pointer move | A dropped ref or handler fails. Evidence gap: no test asserts host attributes, className, style, or xstyle on the row. |
audit:DropdownMenuCheckboxItem/api |
| FR5 | DropdownMenuSelectable.test.tsx "maps a small menu to the small shared checkbox marker" |
Small menu | A marker that ignores the menu size fails. Evidence gap: no test asserts the dropdown-menu-item target on this row. |
audit:DropdownMenuCheckboxItem/theming |
| FR6 | DropdownMenu.test.tsx "arrow navigation reaches consumer-rendered menuitemradio and menuitemcheckbox items" and the disabled-row keyboard cases (component:DropdownMenu FR17) |
Enabled and disabled rows | A row the arrows miss, a disabled row they skip, or a disabled row that toggles or closes the menu fails. | audit:DropdownMenuCheckboxItem/accessibility |
| AR3, PR1 | DropdownMenuForcedColors.test.tsx (the row's :focus-visible ring and token inset); DropdownMenuAudit.a11y.chromium.spec.ts forced-colors frames. Evidence gap: no test asserts the listener bound |
— | — | audit:DropdownMenuCheckboxItem/behavior |
Current-state impact
- Enter keeps the menu open (FR2). Enter on a checkbox row toggles it and
leaves the menu open by default, against the Menu pattern's Enter that
spec:AST-020FR15 adopts, with no named exception (OQ1).
Decision log
No component-local decision.
Open questions
- OQ1 — Does a checkbox row keep the menu open on Enter as a named
exception to the Menu pattern, or close like other rows? (
human-api) Keeping it open lets a person toggle several options in one visit; closing matches the pattern's Enter and the other row types.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or parent contracts. It links to their owners.