An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:CheckboxListItem authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-28 owners: [cixzhang] review_triggers: [ public-api, behavior, layout, interaction, motion, theming, styling, accessibility, visual, react-runtime, compatibility, ] verified_by: [ packages/core/src/CheckboxList/CheckboxList.test.tsx, packages/core/src/CheckboxList/tests/CheckboxList.a11y.chromium.spec.ts, packages/core/src/CheckboxList/tests/CheckboxListPress.a11y.chromium.spec.ts, packages/core/src/CheckboxInput/tests/Checkbox.a11y.test.tsx, packages/core/src/CheckboxInput/tests/Checkbox.a11y.chromium.spec.ts, apps/storybook/rtl-audit/targets.json, scripts/check-knowledge.mjs, ] modules: [] families: [] design_specs: [] architecture: [ architecture:public-component-api, architecture:component-theming-surface, architecture:component-test-sufficiency, architecture:interaction-modality, ] contributing: []
system_specs: [spec:AST-011, spec:AST-021, spec:AST-038, spec:AST-085]
CheckboxListItem component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | One option row: a native checkbox named by label or aria-label, described by description, with optional endContent, rendered through ListItem. Inside a CheckboxList with a value array (collection mode), checked state comes from membership and value is required. Inside List, or inside a CheckboxList without value (standalone mode), the item reads isChecked and calls onCheck. |
| Behavior | The checkbox is the option's only tab stop. Row-surface clicks delegate to it when the item is editable and sits in a CheckboxList or has onCheck, or when it has onClick; an item onClick fires once per direct, keyboard, or row-surface click. Disabled, read-only, and busy states refuse toggling. |
| End-user impact | People can operate each option by pointer, touch, and keyboard, hear its name, description, and checked, mixed, disabled, read-only, or busy state, and see a spinner while it saves. |
| Builder impact | Where the item sits, and whether its parent list has value, selects the mode; value is required only in collection mode. Handlerless meaning, checked-row pointer feedback, consumer DOM-prop targets, read-only click propagation, and focus-ring ownership stay open questions (OQ1, OQ3–OQ6). |
| Compatibility/readiness | A checked, enabled, editable row reflects selected (FR15); no API or default change. Handlerless items and the double focus indicator are listed under Current-state impact. |
| Review checks | Reject a second tab stop, a toggle while disabled, read-only, or busy, isChecked overriding a parent value array, an onClick that fires more than once per click, a dropped description relationship, or a new target, state, or event-routing API introduced without an owner decision. |
| Governing rules | architecture:public-component-api/INV5–INV9; architecture:component-theming-surface/INV3–INV6; architecture:interaction-modality/INV1–INV5; architecture:component-test-sufficiency/INV1–INV7; spec:AST-021/FR8–FR10; spec:AST-085/FR1, FR7; spec:AST-011; spec:AST-038/FR7; WCAG 2.2 1.3.1, 2.1.1, 4.1.2. |
This table is a review projection; the body below is authoritative.
Intent
Present one independent choice as a full-width row whose checkbox, label, description, and end content stay aligned with its checked, available, read-only, and busy state, inside a CheckboxList or a plain List.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: records shipped behavior; no public prop, default, export, or DOM change
- Controlled/uncontrolled behavior: controlled only — by the parent list's
valuein collection mode, byisCheckedin standalone mode - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- One option row: its CheckboxInput, naming (string label, rich label through
aria-labelledby,aria-labeloverride), description relationship, end-content slot, and the checkbox size that follows list density. - Mode resolution: collection membership versus standalone
isCheckedandonCheck, the error for a missingvaluein collection mode, and the next value the row proposes. - Row-surface click delegation, the single-tab-stop rule, and item
onClickrouting. - Item disabled and loading states, the busy rendering of a pending collection item, read-only rendering, and the checked-row fill.
Does not own / non-goals
- The group, its label, description, status, disabled reason, read-only and
disabled inputs, pending-value set, and collection change ordering — owned by
component:CheckboxList. - Row presentation, density, dividers, hover and pressed overlays, the
focus-within ring, the
list-itemtarget, and label and description truncation — owned bycomponent:Listand Item. - The checkbox control, its indicator, focus ring, pressed overlay, and busy,
disabled, and read-only semantics — owned by
component:CheckboxInputand CheckboxIndicator. - Loading-indicator presentation — owned by
component:Spinner; delegation mechanics — owned by the shared clickable-container hook. - New targets, reflected states, or event-routing API.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| naming | string label; node label; aria-label |
Names the checkbox; a node label names it from its visible text; aria-label replaces the derived name on the checkbox, not the row. |
All states. | label required | caller and component | stable | rejected by the public type |
| mode | collection (parent has value); standalone in CheckboxList without value; standalone in List |
Collection reads membership and reports through the parent; standalone reads isChecked and calls onCheck. |
Chosen by placement; isChecked and onCheck are ignored in collection mode. |
standalone | component | stable | a collection item without value throws |
| checked state | unchecked, checked, mixed (standalone only) | Native checkbox state; mixed uses the native indeterminate property and proposes true. |
All modes. | unchecked | caller | stable | rejected by the public type |
| change path | parent onChange/changeAction (collection); onCheck (standalone); none |
Proposes the next value array or boolean. | Enabled, editable, non-busy items. | none | caller and component | shipped; handlerless meaning unsettled | no handler means no component-owned mutation |
| availability | enabled; item isDisabled; group disabled; group disabled with reason |
Blocks toggling and the checked-row fill; the checkbox stays focusable through aria-disabled. |
Item and group. | enabled | component | stable | boolean only |
| read-only | from the group's isReadOnly |
Keeps the value visible, focusable, and full-opacity while refusing toggles. | Inside CheckboxList only. | false | component | stable | boolean only |
| busy | isLoading; pending parent changeAction for the item's value |
Spinner in the checkbox, busy row and checkbox, toggling refused. | Per item. | idle | component | stable | boolean/transition state only |
| content | description, endContent |
Description describes the checkbox; end content stays caller-owned and outside the name. | All states. | none | caller | stable | typed values only |
onClick |
fires on the checkbox for direct, keyboard, and row-surface clicks | Once per click, including read-only items; the public type names the row element. | All states. | none | caller and component | shipped; target unsettled | — |
| pass-through | ref, className, style, xstyle, data, ARIA except aria-label, other events |
Reach the row <li>; consumer xstyle composes after the checked-row fill. |
All states. | none | component | shipped; ARIA target unsettled | component-owned attributes win |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | The row MUST render one native CheckboxInput as ListItem start content; that checkbox MUST be the option's only focusable control, and the row itself MUST NOT be focusable. | shipped source; focused tests; WCAG 2.1.1 and 4.1.2 |
| FR2 | A string label MUST name the checkbox; a node label MUST name it from the visible label element through aria-labelledby; aria-label MUST replace the derived name on the checkbox and never reach the row. |
shipped source and focused tests |
| FR3 | A renderable description MUST describe the checkbox through aria-describedby; an absent or empty description MUST add none. |
shipped source and focused tests; WCAG 1.3.1 |
| FR4 | Inside a CheckboxList with a value array, the item MUST read checked state from membership, throw without value, and propose the array with its value added or removed through the parent's change path; isChecked and onCheck MUST be ignored. |
shipped source and focused tests |
| FR5 | Inside List, or inside a CheckboxList without value, the item MUST read isChecked and call onCheck with the next boolean; a mixed item MUST propose true, and value MAY be omitted. The mixed-state gap component:CheckboxInput FR1 records applies when the mixed value is kept. |
shipped source and focused tests |
| FR6 | Item isDisabled or a disabled group MUST make the checkbox focusable-disabled through aria-disabled (component:CheckboxInput FR4), refuse toggling, and omit the checked-row fill; a group reason adds the group tooltip (component:CheckboxList FR9). |
shipped source, focused tests, and shared checkbox binding |
| FR7 | Item isLoading, or a pending parent changeAction for the item's value, MUST render Spinner inside the checkbox, mark the row and the checkbox busy, and refuse toggling. |
shipped source, focused tests, and the Chromium accessibility suite |
| FR8 | A read-only group MUST make the checkbox read-only, focusable, and full-opacity, refuse every toggle, and omit the checked-row fill; the row delegates clicks only when the item has onClick. |
shipped source, focused tests, and shared checkbox binding; spec:AST-011 |
| FR9 | On an enabled, editable item inside a CheckboxList or with onCheck, a row-surface click outside interactive descendants MUST be delegated to the checkbox; links and buttons in the label, description, or end content MUST keep their own behavior. |
shipped source and focused tests |
| FR10 | An item onClick MUST fire once for each direct, keyboard, or row-surface click, including on read-only items. |
shipped source and focused tests; architecture:public-component-api/INV5 |
| FR11 | compact density MUST render the sm checkbox; other densities MUST render md. |
shipped source and focused test |
| FR12 | An enabled, editable, checked row MUST paint the --color-accent-muted fill, and consumer xstyle MUST compose after it. |
shipped source and the Chromium accessibility suite |
| FR13 | ref, className, style, xstyle, data attributes, ARIA other than aria-label, and events other than onClick MUST reach the row <li>. |
shipped source and focused tests |
| FR14 | A standalone item with isChecked and no onCheck changes nothing on activation. Implementation gap: it declares no read-only state, so the checkbox is exposed as editable (WCAG 2.2 4.1.2); inside a CheckboxList without value, its row also delegates clicks and shows pointer feedback. Its meaning is OQ1. |
exact spec:AST-021 known failure list-item-handlerless-read-only; WCAG 4.1.2 |
| FR15 | A checked, enabled, editable row paints the checked-row fill and reflects a selected state on the row's item and list-item targets, so a theme can restyle checked rows and the text on that fill (architecture:component-theming-surface INV6). A read-only or disabled row paints no fill and reflects no state; its targets match unchecked rows. |
architecture:component-theming-surface/INV6 |
| FR16 | Shipped behavior, not a requirement until its open question is ruled: consumer DOM inputs split between two elements: data attributes and ARIA reach the row, while onClick runs on the checkbox and is typed for the row, so event.currentTarget is the checkbox and does not carry the row's data attributes (OQ3). |
architecture:public-component-api/INV5; INV9 for any retype or move |
| FR17 | Shipped behavior, not a requirement until its open question is ruled: on a read-only item with onClick, the item stops the click's propagation, so React ancestors never receive those clicks, while they do for enabled items (OQ4). The item's own onClick still fires once per click (FR10). |
Current source; shared clickable-container hook behavior |
| FR18 | Shipped behavior, not a requirement until its open question is ruled: on an enabled, editable, checked row, the checked-row fill replaces the row's hover and pressed overlays, so pointer hover and hold give no row feedback (OQ5). | the Chromium accessibility suite; design:user-states leaves hover and selection treatment outside its current claim |
| FR19 | One keyboard focus move paints two indicators: Item's row focus-within outline and CheckboxInput's indicator ring (OQ6). One focus move MUST have one owning indicator (architecture:interaction-modality INV3). Implementation gap: both indicators paint. |
the Chromium accessibility suite; architecture:interaction-modality/INV3 |
Allowed variation
- AV1 — Content. Label, description, and end content may vary within their public types without becoming new targets.
- AV2 — Composed presentation. Density, dividers, row overlays, the focus ring, and the checkbox indicator remain capabilities of their owning components.
- AV3 — Theme paint. Semantic tokens and composed targets may change admitted visual properties without changing semantics, tab order, or state precedence.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Collection option | Checked from membership; one tab stop; toggles through the parent | Label, description, end content |
| Standalone option (List or group) | Reads isChecked, calls onCheck; mixed proposes true |
Placement |
| Busy option | Spinner, busy row and checkbox, toggling refused | Loading source (prop or pending save) |
| Read-only option | Visible, focusable, full-opacity, immutable; onClick fires once per click |
Whether the item has onClick |
| Disabled option | Inoperable; no checked-row fill | Item or group source; group reason |
| Handlerless standalone option | Inert; declares no read-only state (FR14, OQ1) | — |
Transformation and precedence order
- ORD1 — Checked state. Parent
valuearray (collection) → optimistic pending value → membership; otherwiseisChecked; otherwise unchecked. - ORD2 — Toggle. disabled, read-only, or busy guard → mode → parent
onChange(collection) oronCheck(standalone). - ORD3 — Click routing. Interactive descendants keep their clicks → other
row-surface clicks delegate to the checkbox when the item is editable and sits
in a CheckboxList or has
onCheck, or hasonClick→ the checkbox's click runsonClickonce. - ORD4 — Attributes. Consumer rest props → row
<li>;aria-labelandonClick→ checkbox; component-owned name, description, state, and busy attributes win.
Performance and resources
- PR1 — Bounded resources. The item owns no observer, timer, or global listener; delegation listeners belong to the row and its lifetime.
Current measurements belong in the audit record; this subsection owns only durable constraints and their verification target.
Accessibility contract
- AR1 — Option semantics. Each option MUST remain a native checkbox whose name, description, checked or mixed state, and disabled, read-only, and busy states are programmatically determinable.
- AR2 — Keyboard parity. Tab MUST reach the checkbox exactly once, and Space MUST follow the same availability and change rules as pointer activation.
- AR3 — Enlarged target. The row surface MUST act as the checkbox's pointer and touch target without becoming a second control. Under a coarse pointer, a finger held on the box of a click-delegating row presses and paints the whole row, as a press on the row does (owner pass, 2026-11-04).
- AR4 — Busy perception. A busy option MUST expose busy state in the accessibility tree and visibly through Spinner.
- AR5 — Focus visibility. Keyboard focus on the checkbox MUST stay visible; two indicators paint today (FR19, OQ6).
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Option row | Full-width row with start checkbox, label and description, and end content. | List and Item | Supporting | FR1, FR9, FR13 |
| Checkbox | Presents the option's selection indicator. | CheckboxInput owner and design:user-states for its press |
Prominent | FR1, FR6–FR8, FR11 |
| Label, description | Name and describe the checkbox. | Item | Primary content | FR2, FR3 |
| Checked-row fill | Supplements the checkbox state on enabled, editable checked rows. | row selected state (FR15); FR18 open |
Supporting | FR12 |
| Spinner | Replaces the mark while the option is busy. | Spinner | Supporting | FR7 |
This record carries no anatomy-theming map. The composed option anatomy and its
target dispositions are recorded in component:CheckboxList's theming anatomy,
and CheckboxListItem owns no target of its own.
Family and system relationships
component:CheckboxListcomposes this contract: it supplies the collection value, availability, read-only, and pending values the option reads through context, and owns the group around it.architecture:public-component-apiowns pass-through preservation, event composition, refs, and released-change rules.architecture:component-theming-surfaceowns target placement and state reflection.architecture:interaction-modalityowns focus visibility and the one-indicator rule.spec:AST-021owns the reusable checkbox accessibility binding for CheckboxListItem and its exact known-failure lifecycle.spec:AST-011recordsisReadOnlyas the name for visible, focusable, non-editable values.spec:AST-038/FR7stops CheckboxList context at a layer boundary; an item inside a layer needs its own provider.- List, Item, CheckboxInput, CheckboxIndicator, and Spinner retain their existing target and behavior contracts when composed here.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR9, AR2, AR3 | CheckboxList.test.tsx single-tab-stop, row-click, link-in-label, and interactive end-content cases |
Collection option; row-surface click; link in a rich label; interactive end content | A second tab stop, lost delegation, or a toggle from an interactive descendant fails. | audit:CheckboxListItem/interaction |
| AR3 (finger) | CheckboxList.test.tsx press-surface cases; CheckboxListPress.a11y.chromium.spec.ts |
Coarse and fine pointer; label, description and box; nested checkbox | A finger on the box that paints only the box, a mouse press that paints the row, or a nested checkbox pressing the row fails. | audit:CheckboxListItem/interaction |
| FR2, FR3, AR1 | CheckboxList.test.tsx accessible-name and description cases; shared checkbox bindings |
String and rich label; aria-label; string and node description; absent description |
A wrong name or description, or aria-label on the row, fails. |
audit:CheckboxListItem/accessibility |
| FR4, FR5 | CheckboxList.test.tsx collection, standalone, and select-all cases |
Add, remove, missing value, mixed, select-all, isChecked with a parent array |
A wrong array or boolean, a missing error, or isChecked overriding membership fails. |
audit:CheckboxListItem/behavior |
| FR6–FR8, AR4 | CheckboxList.test.tsx disabled, loading, pending, and read-only cases; CheckboxList.a11y.chromium.spec.ts disabled-*, loading-item, pending-*, and read-only cases |
Item and group disabled; reason; loading; pending; read-only | A toggle while disabled, read-only, or busy, or a lost busy state, fails. | audit:CheckboxListItem/accessibility |
| FR10, FR17 | CheckboxList.test.tsx item onClick and read-only click cases |
Enabled and read-only; direct, keyboard, and row-surface clicks | An onClick that fires zero or several times per click fails. Evidence gap: no test asserts the stopped propagation on read-only items (FR17). |
audit:CheckboxListItem/behavior |
| FR11 | CheckboxList.test.tsx density case |
Compact and balanced | A wrong checkbox size fails. | audit:CheckboxListItem/layout |
| FR12, FR18 | CheckboxList.a11y.chromium.spec.ts checked, hover-*, and pressed-* cases |
Light and dark; unchecked and checked | A missing or misplaced fill fails the row-paint check. Evidence gap: no assertion that xstyle composes after the fill. |
audit:CheckboxListItem/visual |
| FR13, FR16 | CheckboxList.test.tsx ref and styling, data-testid, and ARIA cases |
Row ref, class, style, data, ARIA | A dropped or misrouted input fails. Evidence gap: no test asserts event.currentTarget for onClick (FR16). |
audit:CheckboxListItem/api |
| FR14 | Checkbox.a11y.test.tsx known failure list-item-handlerless-read-only; CheckboxList.a11y.chromium.spec.ts handlerless case |
Standalone with isChecked and no onCheck |
The recorded known failure stops matching when its gap closes. | audit:CheckboxListItem/accessibility |
| FR15 | CheckboxList.test.tsx checked-row state case |
checked, unchecked, read-only and disabled rows | A checked, enabled, editable row without selected on its row targets fails; a read-only or disabled row with it fails |
current source |
| FR19, AR5 | CheckboxList.a11y.chromium.spec.ts focus-visible and forced-colors-focus cases |
Keyboard focus; forced colors | A lost focus indicator fails. Evidence gap: no test counts focus indicators (FR19). | audit:CheckboxListItem/visual |
| Direction | RTL audit target core-checkboxlist--rich-descriptions (apps/storybook/rtl-audit/targets.json); CheckboxList.a11y.chromium.spec.ts rtl case |
LTR and RTL | The checkbox and end content fail to swap inline order. | audit:CheckboxListItem/layout |
| ORD1–ORD4, PR1 | Covered by the FR4–FR10 and FR13 rows. Evidence gap: no test asserts the absence of observers, timers, or global listeners | — | — | audit:CheckboxListItem/behavior |
Current-state impact
- Handlerless item (FR14). A standalone item with
isCheckedand noonCheckis exposed as an editable checkbox though activation changes nothing (WCAG 2.2 4.1.2). The shared checkbox suite records this as a known failure; the meaning is OQ1. - Mixed state after activation (FR5). A standalone mixed item whose value
stays mixed loses its native mixed state on activation, as
component:CheckboxInputrecords. - Two focus indicators (FR19). Keyboard focus paints both the row outline
and the checkbox ring, against
architecture:interaction-modalityINV3.
Decision log
No component-local decision. CheckboxListItem applies spec:AST-021 and
spec:AST-085.
Open questions
- OQ1 — What does a standalone item with
isCheckedand noonCheckmean? (human-api) Choose read-only, unavailable, or invalid usage, consistent with the matching CheckboxInput question. - OQ3 — Which element owns consumer DOM inputs? (
human-api) Data and ARIA reach the row whileonClickruns on the checkbox under a row-typed handler. - OQ4 — Should read-only item clicks propagate? (
human-api) No current authority owns ancestor propagation. The stop exists because the shared clickable-container hook would otherwise re-delegate a click that came from itsaria-readonlydelegate target back to it. - OQ5 — What hover and pressed feedback should a checked row show?
(
human-design) The checked-row fill currently replaces both overlays. - OQ6 — Which element paints the option's focus ring? (
human-design)architecture:interaction-modality/INV3requires one indicator; RadioList composes the same two painters.
Content boundary
This file does not duplicate consumer prop tables and examples, current audit results, implementation steps, or the group contract. It links to their owners.