Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(CheckboxList): an optional checkbox group can say so with isOptional (#8770)

ksyingcd1e42cec8ef
diff --git a/.changeset/checkbox-list-is-optional.md b/.changeset/checkbox-list-is-optional.md
new file mode 100644
index 0000000000..674c407372
--- /dev/null
+++ b/.changeset/checkbox-list-is-optional.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] `CheckboxList` takes `isOptional`, as `RadioList` and `CheckboxInput` do. It shows the optional indicator after the group label, so an optional checkbox group can say so, including as the exception in a `FormLayout` with `defaultOptionality="required"`. Under `defaultOptionality="optional"` the indicator stays hidden, as for every field. A checkbox group takes no required state from a form default: with or without `isOptional`, its checkboxes carry no `aria-required` from it, and it adds no native `required`.
+
+@ksying
diff --git a/apps/storybook/stories/CheckboxList.stories.tsx b/apps/storybook/stories/CheckboxList.stories.tsx
index a61b5ec473..2dff2991c3 100644
--- a/apps/storybook/stories/CheckboxList.stories.tsx
+++ b/apps/storybook/stories/CheckboxList.stories.tsx
@@ -331,6 +331,25 @@ export const DisabledItem: Story = {
},
};
+export const Optional: Story = {
+ render: args => {
+ const [value, setValue] = useState<string[]>([]);
+ const {value: _value, onChange: _onChange, ...restArgs} = args;
+ return (
+ <CheckboxList {...restArgs} value={value} onChange={setValue}>
+ <CheckboxListItem label="Email" value="email" />
+ <CheckboxListItem label="SMS" value="sms" />
+ <CheckboxListItem label="Push notification" value="push" />
+ </CheckboxList>
+ );
+ },
+ args: {
+ label: 'Notification preferences',
+ description: 'Leave all unchecked to receive no notifications.',
+ isOptional: true,
+ },
+};
+
export const WithErrorStatus: Story = {
render: args => {
const [value, setValue] = useState<string[]>([]);
diff --git a/docs/specs/components/CheckboxList/CheckboxList.spec.md b/docs/specs/components/CheckboxList/CheckboxList.spec.md
index 11a47cbce7..f474466992 100644
--- a/docs/specs/components/CheckboxList/CheckboxList.spec.md
+++ b/docs/specs/components/CheckboxList/CheckboxList.spec.md
@@ -57,7 +57,7 @@ system_specs: [spec:AST-011, spec:AST-021, spec:AST-038, spec:AST-085]
| 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 `value`s. The rendering of a status without a message stays an open question here (OQ3); per-option open questions are in `component:CheckboxListItem`. |
-| Compatibility/readiness | Records shipped behavior. Each checkbox gains `aria-invalid` under an error status; no API or default change. |
+| Compatibility/readiness | Adds `isOptional` (FR16), 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. |
@@ -72,8 +72,9 @@ touch, keyboard, and assistive technology.
## Compatibility and migration
- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, or
- export change; each checkbox gains `aria-invalid` under an error status
+- Compatibility class: additive `isOptional` (FR16), default `false`; no other
+ public prop, default, or export change; each checkbox gains `aria-invalid`
+ under an error status
- Controlled/uncontrolled behavior: collection mode is controlled by `value`;
standalone items follow `component:CheckboxListItem`; no uncontrolled mode
exists
@@ -114,6 +115,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| 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` | Shows Field's optional indicator after the group label. | 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 |
@@ -129,18 +131,19 @@ 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` |
+| 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 group sets no native `required`. | CheckboxInput and RadioList parity; WAI-ARIA 1.2 `group` has no `aria-required`, and `aria-required` on each checkbox would require every option |
Per-option requirements are owned by `component:CheckboxListItem`
(`architecture:knowledge-contracts/INV2`).
@@ -288,17 +291,18 @@ row surface, but not a checked-row state (`component:CheckboxListItem` FR15).
## 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` |
-| 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` |
+| 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` |
+| 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`
diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
index ca3f2075ee..8165761354 100644
--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs
+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
@@ -127,6 +127,13 @@ export const docs = {
type: 'string',
description: 'Description text displayed below the label.',
},
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description:
+ 'Whether the group is optional. Shows the optional indicator after the group label, unless a surrounding FormLayout already makes fields optional by default.',
+ default: 'false',
+ },
{
name: 'density',
type: "'compact' | 'balanced' | 'spacious'",
diff --git a/packages/core/src/CheckboxList/CheckboxList.test.tsx b/packages/core/src/CheckboxList/CheckboxList.test.tsx
index 36866eb64e..8857c399a9 100644
--- a/packages/core/src/CheckboxList/CheckboxList.test.tsx
+++ b/packages/core/src/CheckboxList/CheckboxList.test.tsx
@@ -24,6 +24,7 @@ import {CheckboxListItem} from './CheckboxListItem';
import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
import {__resetInteractionModalityForTest} from '../utils/interactionModality';
import {List} from '../List/List';
+import {FormLayout} from '../FormLayout/FormLayout';
// FieldStatus announces status messages through the persistent useAnnounce
// singletons; remove them between tests so role/aria-live queries in this
@@ -110,6 +111,106 @@ describe('CheckboxList', () => {
expect(group.getAttribute('aria-labelledby')).toBe(label.id);
});
+ it('shows the optional indicator after the group label with isOptional', () => {
+ const {rerender} = render(
+ <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+ <CheckboxListItem label="Option A" value="a" />
+ </CheckboxList>,
+ );
+ expect(screen.queryByText('Optional')).not.toBeInTheDocument();
+
+ rerender(
+ <CheckboxList
+ label="Preferences"
+ value={[]}
+ onChange={() => {}}
+ isOptional>
+ <CheckboxListItem label="Option A" value="a" />
+ </CheckboxList>,
+ );
+ const label = screen.getByText('Preferences');
+ expect(within(label).getByText('Optional')).toBeInTheDocument();
+ // A checkbox group has no required state to announce or validate.
+ expect(
+ screen.getByRole('group', {name: /^Preferences/}),
+ ).not.toHaveAttribute('aria-required');
+ expect(screen.getByRole('checkbox', {name: 'Option A'})).not.toBeRequired();
+ });
+
+ it('marks isOptional only where it deviates from the FormLayout default', () => {
+ const {rerender} = render(
+ <FormLayout defaultOptionality="required">
+ <CheckboxList
+ label="Preferences"
+ value={[]}
+ onChange={() => {}}
+ isOptional>
+ <CheckboxListItem label="Option A" value="a" />
+ <CheckboxListItem label="Option B" value="b" />
+ </CheckboxList>
+ </FormLayout>,
+ );
+ expect(screen.getByText('Optional')).toBeInTheDocument();
+ // The checkboxes follow the group, not the required form default.
+ for (const checkbox of screen.getAllByRole('checkbox')) {
+ expect(checkbox).not.toHaveAttribute('aria-required');
+ }
+
+ rerender(
+ <FormLayout defaultOptionality="optional">
+ <CheckboxList
+ label="Preferences"
+ value={[]}
+ onChange={() => {}}
+ isOptional>
+ <CheckboxListItem label="Option A" value="a" />
+ </CheckboxList>
+ </FormLayout>,
+ );
+ expect(screen.queryByText('Optional')).not.toBeInTheDocument();
+ });
+
+ it('gives an unmarked group no aria-required under a required FormLayout default', () => {
+ render(
+ <FormLayout defaultOptionality="required">
+ <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+ <CheckboxListItem label="Option A" value="a" />
+ <CheckboxListItem label="Option B" value="b" />
+ </CheckboxList>
+ </FormLayout>,
+ );
+ expect(screen.queryByText('Optional')).not.toBeInTheDocument();
+ expect(
+ screen.getByRole('group', {name: 'Preferences'}),
+ ).not.toHaveAttribute('aria-required');
+ for (const checkbox of screen.getAllByRole('checkbox')) {
+ expect(checkbox).not.toHaveAttribute('aria-required');
+ expect(checkbox).not.toBeRequired();
+ }
+ });
+
+ it('keeps a focused checkbox focused when isOptional changes', () => {
+ const {rerender} = render(
+ <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+ <CheckboxListItem label="Option A" value="a" />
+ </CheckboxList>,
+ );
+ const checkbox = screen.getByRole('checkbox', {name: 'Option A'});
+ checkbox.focus();
+
+ rerender(
+ <CheckboxList
+ label="Preferences"
+ value={[]}
+ onChange={() => {}}
+ isOptional>
+ <CheckboxListItem label="Option A" value="a" />
+ </CheckboxList>,
+ );
+ expect(screen.getByRole('checkbox', {name: 'Option A'})).toBe(checkbox);
+ expect(checkbox).toHaveFocus();
+ });
+
it('renders checkbox items', () => {
render(
<CheckboxList label="Preferences" value={[]} onChange={() => {}}>
diff --git a/packages/core/src/CheckboxList/CheckboxList.tsx b/packages/core/src/CheckboxList/CheckboxList.tsx
index 3007a609d4..aa0b5605b3 100644
--- a/packages/core/src/CheckboxList/CheckboxList.tsx
+++ b/packages/core/src/CheckboxList/CheckboxList.tsx
@@ -65,6 +65,13 @@ export interface CheckboxListProps extends Omit<
* Description text displayed below the label.
*/
description?: string;
+ /**
+ * Whether the group is optional. Shows the optional indicator after the
+ * group label, unless a surrounding `FormLayout` already makes fields
+ * optional by default.
+ * @default false
+ */
+ isOptional?: boolean;
/**
* Status indicator for the checkbox group.
* When set with a message, displays a colored message box below the group.
@@ -153,6 +160,7 @@ export function CheckboxList({
label,
isLabelHidden = false,
description,
+ isOptional = false,
status,
value,
onChange,
@@ -270,6 +278,7 @@ export function CheckboxList({
inputID={inputID}
labelID={labelID}
isGroupLabel
+ isOptional={isOptional}
descriptionID={description ? descriptionID : undefined}
isDisabled={isDisabled}
status={