An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:CheckboxList 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/CheckboxInput/tests/Checkbox.a11y.test.tsx, packages/core/src/CheckboxInput/tests/Checkbox.a11y.chromium.spec.ts, packages/core/src/theme/themingTargets.test.ts, packages/core/src/CheckboxList/CheckboxList.fr10.test.tsx, packages/core/src/CheckboxList/CheckboxList.required.test.tsx, scripts/check-knowledge.mjs, ] modules: [] families: [family:input-fields] 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]
CheckboxList component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | CheckboxList is a labeled role="group" of CheckboxListItem rows. A value array selects controlled collection mode (onChange, changeAction); without it, its items are standalone. The group owns naming, description, disabled, disabled-reason, read-only, pending values, and status. Each option's behavior is component:CheckboxListItem. |
| Behavior | The group names and describes its options, tracks every value whose changeAction is pending so each saving option stays busy while the others stay interactive, and applies disabled, read-only, and status to every option. |
| End-user impact | People can identify the group, operate every option by pointer, touch, and keyboard, learn why a group is unavailable, and see which options are still saving. |
| Builder impact | Builders choose collection mode by passing value, and then supply stable item values. The rendering of a status without a message stays an open question here (OQ3); per-option open questions are in component:CheckboxListItem. |
| Compatibility/readiness | Adds isOptional (FR16) and isRequired (FR17), each default false. Each checkbox gains aria-invalid under an error status; no other API, default, or DOM change. |
| Review checks | Reject a pending value that loses its busy state or re-toggle guard when another option is toggled, dropped group naming or description ids, a toggle while the group is disabled or read-only, or new target or state API introduced without an owner decision. Per-option checks are in component:CheckboxListItem. |
| Governing rules | architecture:public-component-api/INV1–INV9; architecture:component-theming-surface/INV3–INV6; architecture:interaction-modality/INV1–INV5; architecture:component-test-sufficiency/INV1–INV7; architecture:knowledge-contracts/INV2; spec:AST-021/FR8–FR10; spec:AST-038/FR7; spec:AST-085/FR1, FR7; family:input-fields/FR10; 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 a small, labeled set of independent checkbox options whose checked, available, read-only, busy, and status states stay aligned across pointer, touch, keyboard, and assistive technology.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: additive
isOptional(FR16) andisRequired(FR17), each defaultfalse; no other public prop, default, or export change; each checkbox gainsaria-invalidunder an error status - Controlled/uncontrolled behavior: collection mode is controlled by
value; standalone items followcomponent:CheckboxListItem; no uncontrolled mode exists - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The labeled checkbox group, its
checkbox-listtarget, the group's description, status, and disabled-reason relationships, and where its base,container*, andcontrol*props land. - Collection state shared with CheckboxListItem: checked membership, change ordering, optimistic pending values, and group-level availability.
- The composed option anatomy and its target dispositions (Theming anatomy below).
Does not own / non-goals
- Each option's behavior — its checkbox, naming and description, standalone
mode, row-surface delegation and
onClickrouting, item disabled and loading states, density sizing, and checked-row fill — owned bycomponent:CheckboxListItem. - List and option-row presentation — owned by
component:List; itslist-itemtarget reaches only the row root. - The checkbox control, its indicator, focus ring, and pressed overlay — owned
by
component:CheckboxInputand CheckboxIndicator. - Group-label and validation-message presentation — owned by Field under
family:input-fields(shared owner section) andcomponent:FieldStatus. - Loading-indicator presentation — owned by
component:Spinner; tooltip behavior — owned byuseTooltip. - New targets or reflected states for the row, descriptions, or caller content.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| group naming | label, isLabelHidden, description |
Names and describes the role="group"; a hidden label still names it. |
All states. | label required; visible | caller and Field | stable | rejected by the public type |
| optionality | isOptional, isRequired |
Shows Field's optional or required indicator after the group label; isRequired also needs one checked box (FR17). |
All states. | false | caller and Field | stable | boolean only |
| collection value | value array present or absent |
Present: the group owns checked membership and change handling for its items. Absent: its items are standalone. | All states. | absent | caller and component | stable | an item without value in collection mode throws (item FR4) |
| change path | onChange, changeAction, both, neither |
Reports the next value array; changeAction runs after onChange in a transition with an optimistic value. |
Collection mode. | neither | caller and component | shipped; handlerless meaning unsettled | no handler means no component-owned mutation |
| availability | enabled, isDisabled, isDisabled with disabledMessage |
Blocks toggling on every item, which stays focusable through aria-disabled; a reason adds a group tooltip. |
Reason applies only with isDisabled. |
enabled | component | stable | a reason without isDisabled renders nothing |
| read-only | isReadOnly |
Makes every item read-only. | Group-wide. | false | component | stable | boolean only |
| pending values | the values whose changeAction is pending |
Each pending value's item renders busy; toggling another item does not clear it; concurrent values settle together. | Collection mode with changeAction. |
none | component | stable | transition state only |
| status | warning, error, success, optional message |
A message renders a detached FieldStatus after the list and describes the group; an error makes each checkbox aria-invalid. |
All states. | none | caller and FieldStatus | shipped | a status without a message renders nothing |
| row layout | density compact/balanced/spacious; hasDividers; width |
Density reaches the List and its rows; dividers separate rows; width sizes the label, list, and status together. | All states. | balanced; none; intrinsic | component and List | stable | rejected by the public types |
| pass-through | CheckboxList rest, ref, container*, control* |
Base props and ref reach the role="group"; container* the Field box; control* the group element. |
All states. | none | component | stable | root xstyle, className, style are not accepted |
Item props (label, aria-label, description, endContent, isChecked,
onCheck, item isDisabled, isLoading, and item pass-through) are concepts
of component:CheckboxListItem.
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | The render MUST place CheckboxListItem children inside a List within a role="group" named by the group label through aria-labelledby; its aria-describedby MUST list any caller description, then the description, status message, and disabled-reason tooltip that are present, in that order. |
shipped source; focused tests; WCAG 1.3.1 and 4.1.2 |
| FR2 | The CheckboxList root MUST carry the current checkbox-list target. |
shipped source and public docs |
| FR4 | A status message MUST render through a detached FieldStatus after the list. | shipped source, focused tests, and the Chromium accessibility suite |
| FR6 | With a value array, the group MUST provide membership to its items, call onChange with the next array an item proposes (component:CheckboxListItem FR4), and then run changeAction with the same array in a transition with an optimistic value. |
shipped source and focused tests |
| FR7 | The group MUST track every value whose changeAction is pending and expose it to its items, each of which renders busy (component:CheckboxListItem FR7); toggling another item MUST NOT clear an earlier pending value. Concurrent pending values settle together, after which every busy state clears. |
shipped public changeAction promise; focused regression test; the Chromium accessibility suite |
| FR9 | Group isDisabled MUST make every checkbox focusable-disabled through aria-disabled (component:CheckboxInput FR4) and refuse toggling, and MUST set aria-disabled="true" on the role="group" element, as component:ButtonGroup FR1 does. With disabledMessage, the reason tooltip opens on group hover and keyboard focus, and the reason MUST describe each focusable checkbox (spec:AST-085 FR5, FR7). Implementation gap: the reason describes only the role="group", so a focused checkbox is not described by it. |
spec:AST-085 FR1, FR7; shipped source, focused tests, and shared checkbox binding |
| FR10 | Group isReadOnly MUST make every item in the group read-only (component:CheckboxListItem FR8 and FR10). |
shipped source; shared checkbox binding; spec:AST-011 read-only vocabulary |
| FR13 | density MUST reach the List and its rows (the checkbox size follows component:CheckboxListItem FR11); hasDividers MUST separate rows without a divider after the last row; width MUST size the label, list, and status together. |
shipped source, docs, and the Chromium accessibility suite |
| FR14 | An error status with a message renders it (FR4), and an error status makes every checkbox aria-invalid="true", so a screen reader announces the invalid state as each checkbox takes focus. Implementation gap: a status without a message renders nothing; its meaning is OQ3. |
shipped source; spec:AST-002/FR15 |
| FR15 | Base props, including ARIA and ref, MUST reach the role="group"; a caller aria-labelledby joins the group label and a caller aria-describedby comes first. container* MUST reach the Field box where one renders (in a horizontal-labels FormLayout none renders, and container* has no effect and warns), and control* the group element; root xstyle, className, and style are not accepted. |
family:input-fields FR10; CheckboxList.fr10.test.tsx |
| FR16 | isOptional MUST reach the group's Field as isOptional, so the group label shows the optional indicator unless the nearest FormLayout defaults fields to optional (component:FormLayout FR5). An empty selection is an answer, so a checkbox group takes no required state from a form default (component:FormLayout FR5's exception): with or without isOptional, its checkboxes carry no aria-required from it, and the form default puts no native required on them. |
CheckboxInput and RadioList parity; WAI-ARIA 1.2 group has no aria-required, and aria-required on each checkbox would require every option |
| FR17 | isRequired marks the group required. Its name shows the input fields' required marker by the same rules every input field follows (family:input-fields), so where a form's default already marks fields required, no marker shows, as for any field. While no checkbox is checked, the first checkbox that is neither disabled nor read-only carries native required, so the browser blocks submit and focuses it with its own message; once any box is checked, no box carries required. An empty group is missing; the app's status stays the visible error text, and Astryx adds no message of its own. |
Owner decision; family:input-fields; HTML constraint validation |
Per-option requirements are owned by component:CheckboxListItem
(architecture:knowledge-contracts/INV2).
Allowed variation
- AV1 — Group content. The label, description, status message, and width may vary within their public types.
- AV2 — Theme paint. The
checkbox-listtarget and the composed group targets may change admitted visual properties without changing semantics or state precedence.
Option variation is component:CheckboxListItem AV1–AV3.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Default collection | Named group, options list, and rows render; membership reaches every item | Option content and selected values |
| Pending values | Each pending value keeps its item busy until every pending value settles | Which options are pending |
| Group disabled with reason | Checkboxes stay focusable and inoperable; the reason is reachable by hover, focus, and AT | Reason text |
| Group read-only | Every item is read-only | Which values are checked |
| Group status with message | Detached FieldStatus follows the group and describes it | Error, warning, or success status |
Transformation and precedence order
- ORD1 — Checked state. Collection
value→ optimistic pending value → the membership each item reads (component:CheckboxListItemORD1). - ORD2 — Toggle. An item's proposed next array (
component:CheckboxListItemORD2) →onChange→changeActionin a transition that adds the toggled value to the pending set. - ORD3 — Availability. Group disabled wins and keeps every checkbox focusable; a group reason adds the tooltip, not operability; group read-only applies to mutation only.
Performance and resources
- PR1 — Bounded resources. The component owns no observer or global
listener of its own. Tooltip listeners are scoped to the group element and
its lifetime. A required group (FR17) registers its options with Core's
shared mutation observer for its lifetime, so a reorder updates which box
carries
required.
Current measurements belong in the audit record; this subsection owns only durable constraints and their verification target.
Accessibility contract
- AR1 — Group identity. The group name and its description, status, and disabled-reason relationships MUST remain programmatically determinable.
- AR2, AR3, AR5 — Option semantics, keyboard parity, and busy perception are
owned by
component:CheckboxListItemAR1, AR2, and AR4. - AR4 — Disabled reasons. A group reason MUST stay discoverable by keyboard focus and assistive technology while toggling stays blocked.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Group | Contains the current checkbox-group composition. | Current source and public docs | Supporting | FR1, FR2 |
| Options list | Presents the List-owned list and row roots. | Current source | Supporting | FR1, FR13 |
| Option rows | Present each option's checkbox, content, busy spinner, and checked-row fill. | component:CheckboxListItem |
Prominent | component:CheckboxListItem FR1–FR13 |
| Status message | Presents the group's current status. | Current shared-component source | Supporting | FR4 |
Theming anatomy
{
"Group": {"target": "checkbox-list"},
"Group label": {
"delegatesTo": {"owner": "component:Field", "target": "field-label"}
},
"Description": {
"none": {
"reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
}
},
"Options list": {
"delegatesTo": {"owner": "component:List", "target": "list"}
},
"Option row": {
"delegatesTo": {"owner": "component:List", "target": "list-item"}
},
"Checkbox": {
"delegatesTo": {
"owner": "component:CheckboxInput",
"target": "checkbox-indicator"
}
},
"Option label": {
"none": {
"reason": "unsettled: Item rather than Text renders the stable Option label in a separate untargeted span; future exposure still needs an owner decision"
}
},
"Option description": {
"none": {
"reason": "unsettled: Item rather than Text renders the stable Option description in a separate untargeted span; future exposure still needs an owner decision"
}
},
"End content": {
"none": {
"reason": "intentional: End content is caller-provided content outside CheckboxList's public theming ownership"
}
},
"Spinner": {
"delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
},
"Status message": {
"delegatesTo": {
"owner": "component:FieldStatus",
"target": "field-status"
}
}
}
Description remains stable consumer anatomy, but no current public target
reaches it. Item, not Text, renders option labels and descriptions in separate
untargeted spans, so neither delegates to Text nor inherits the row-root
list-item target; future exposure remains unsettled. Rich label content and end
content are caller-provided, and end content intentionally stays outside
CheckboxList's public theming ownership. The Option row delegation reaches the
row surface and, on a checked, enabled, editable row, its selected state
(component:CheckboxListItem FR15).
Family and system relationships
architecture:public-component-apiowns export reachability, pass-through preservation, styling composition, refs, and released-change rules.architecture:component-theming-surfaceowns anatomy qualification, factualnonedispositions, composition-preserving target ownership, and state reflection.architecture:interaction-modalityowns focus visibility and the boundary between the focused checkbox and the element that paints its ring.architecture:knowledge-contracts/INV2keeps each per-option fact incomponent:CheckboxListItemrather than copying it here.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.component:CheckboxListItemowns the per-option contract this group composes.- List, CheckboxInput, Field, FieldStatus, Spinner, and Tooltip retain their existing public target and behavior contracts when composed by CheckboxList.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR1 | CheckboxList.test.tsx group-role, group-description, and disabledMessage cases |
Named group; description plus status; disabled reason | A missing group name, or a description and status out of order, fails. Evidence gap: no test asserts the caller description first or the disabled reason last. | audit:CheckboxList/accessibility |
| FR2, FR15 | CheckboxList.test.tsx ref and container case; CheckboxList.fr10.test.tsx |
Standalone; horizontal-labels FormLayout |
A ref off the group, container* off the Field box, or a base prop off the group fails. |
audit:CheckboxList/api |
| FR4, FR14 | CheckboxList.test.tsx error-status cases, including every checkbox's aria-invalid; CheckboxListErrorStatus.a11y.chromium.spec.ts |
Error with message | A missing status message fails. Evidence gap: no test asserts the empty render without a message. | audit:CheckboxList/accessibility |
| FR6, FR7 | CheckboxList.test.tsx add, remove, and pending cases; CheckboxList.a11y.chromium.spec.ts pending-single, pending-concurrent, and pending-settled cases |
Add; remove; one and two pending values; settled | A wrong array, a cleared earlier pending value, or a busy state that outlives settlement fails. | audit:CheckboxList/behavior |
| FR9, FR10, AR4 | CheckboxList.test.tsx group-disabled (including the group's aria-disabled), disabledMessage, and read-only cases; ListGroupDisabled.a11y.chromium.spec.ts; shared checkbox bindings |
Group disabled; with reason; read-only item | A lost tab stop, a toggle while disabled, or a read-only toggle fails. Evidence gap: no test asserts that a focused checkbox is not described by the reason. | audit:CheckboxList/accessibility |
| FR13 | CheckboxList.test.tsx density cases; CheckboxList.a11y.chromium.spec.ts density, divider, 320-pixel, and RTL cases |
Compact, balanced, spacious; dividers; narrow; RTL | A density, divider, overflow, or direction sensor fails. Evidence gap: no test asserts width sizing the label, list, and status together. |
audit:CheckboxList/layout |
| FR16 | CheckboxList.test.tsx optional-indicator and FormLayout-default cases |
isOptional; unmarked and optional groups under a required default; optional default; toggled with focus |
Dropping isOptional from the Field, showing it under an optional default, a group checkbox with aria-required under a required default, or remounting rows when isOptional changes, fails. |
audit:CheckboxList/accessibility |
| FR17 | CheckboxList.required.test.tsx |
Marker; required-default form; no box checked; one checked; last box unchecked; disabled first box; disabled group; read-only group; standalone items; keyed reorder; item removed | A missing marker, a marker under a required default, a submit with no box checked, a blocked submit with one checked, or required on more than one box, fails. |
audit:CheckboxList/accessibility |
| ORD1–ORD3, PR1 | ORD1 and ORD2 are covered by the FR6 and FR7 rows, ORD3 by the FR9 and FR10 rows. Evidence gap: no test asserts the absence of observers or global listeners | — | — | audit:CheckboxList/behavior |
| Local target source | themingTargets.test.ts; CheckboxList.test.tsx ref and container case |
checkbox-list |
A rendered class absent from the documented targets, or a missing astryx-checkbox-list on the Field root, fails. |
audit:CheckboxList/theming |
| Theming anatomy map | scripts/check-knowledge.mjs |
Canonical anatomy and current local target | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails validation. | audit:CheckboxList/theming |
Per-option verification is owned by component:CheckboxListItem's
verification map. No current repository check resolves delegatesTo
owner and target pairs; the pairs above match the current Field, List,
CheckboxInput, Spinner, and FieldStatus targets.
Current-state impact
- Group reason (FR9). A group
disabledMessagedescribes only therole="group", so a focused disabled checkbox is not described by it, againstspec:AST-085FR5 and FR7. - Status without a message (FR14). A status without a message renders nothing; its meaning is OQ3.
- Required announcement (FR17).
role="group"cannot carryaria-required, and browsers expose an uncheckedrequiredcheckbox as invalid rather than required, so while the group is empty its first checkbox alone reports that state, as aCheckboxInputwithisRequireddoes today; a requiredRadioListkeeps each radio's invalid state on its status instead (component:RadioListFR6).
Decision log
No component-local decision. CheckboxList applies spec:AST-021,
spec:AST-085, and family:input-fields FR10.
Open questions
- OQ3 — What should a status without a message render? (
human-api) Per-option questions live incomponent:CheckboxListItem.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, the per-option contract, or shared-component contracts. It links to their owners.