Skip to content

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

TypeScript

fix(checkboxlist): wrap items in a labeled role=group (forms audit) (#3456)

Cindy Zhanga036a3dc7c08
diff --git a/.changeset/checkboxlist-group-label.md b/.changeset/checkboxlist-group-label.md
new file mode 100644
index 0000000000..97d2118712
--- /dev/null
+++ b/.changeset/checkboxlist-group-label.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] CheckboxList: the checkboxes are now wrapped in a `role="group"` named by the field label via `aria-labelledby` (and associated with the description/error), instead of a flat list with an orphaned label `htmlFor`. Screen-reader users now hear the group's name and context (#3343).
+@cixzhang
diff --git a/packages/core/src/CheckboxList/CheckboxList.test.tsx b/packages/core/src/CheckboxList/CheckboxList.test.tsx
index 9267eebbc1..da35dfa4c8 100644
--- a/packages/core/src/CheckboxList/CheckboxList.test.tsx
+++ b/packages/core/src/CheckboxList/CheckboxList.test.tsx
@@ -26,6 +26,25 @@ describe('CheckboxList', () => {
expect(screen.getByText('Preferences')).toBeInTheDocument();
});
+ it('wraps items in a group named by the label (forms audit: group role)', () => {
+ render(
+ <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+ <CheckboxListItem label="Option A" value="a" />
+ </CheckboxList>,
+ );
+ // The checkboxes are wrapped in a role="group" whose accessible name comes
+ // from the field label (via aria-labelledby). The label is rendered as a
+ // <span> (not a literal <label>, which can't name a group) with no
+ // orphaned htmlFor.
+ const group = screen.getByRole('group', {name: 'Preferences'});
+ expect(group).toBeInTheDocument();
+ const label = screen.getByText('Preferences');
+ expect(label.tagName).toBe('SPAN');
+ expect(label.closest('label')).toBeNull();
+ expect(label).not.toHaveAttribute('for');
+ expect(group.getAttribute('aria-labelledby')).toBe(label.id);
+ });
+
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 ec7a651373..94a5406010 100644
--- a/packages/core/src/CheckboxList/CheckboxList.tsx
+++ b/packages/core/src/CheckboxList/CheckboxList.tsx
@@ -151,6 +151,7 @@ export function CheckboxList({
'data-testid': dataTestId,
}: CheckboxListProps) {
const inputID = useId();
+ const labelElementID = useId();
const descriptionID = useId();
const statusMessageID = useId();
@@ -210,6 +211,8 @@ export function CheckboxList({
isLabelHidden={isLabelHidden}
description={description}
inputID={inputID}
+ labelElementID={labelElementID}
+ isGroupLabel
descriptionID={description ? descriptionID : undefined}
isDisabled={isDisabled}
status={
@@ -226,9 +229,21 @@ export function CheckboxList({
xstyle={xstyle}
{...mergeProps(themeProps('checkbox-list'), {className, style})}>
<CheckboxListContext value={contextValue}>
- <List density={density} hasDividers={hasDividers}>
- {children}
- </List>
+ <div
+ role="group"
+ aria-labelledby={labelElementID}
+ aria-describedby={
+ [
+ description ? descriptionID : null,
+ status?.message ? statusMessageID : null,
+ ]
+ .filter(Boolean)
+ .join(' ') || undefined
+ }>
+ <List density={density} hasDividers={hasDividers}>
+ {children}
+ </List>
+ </div>
</CheckboxListContext>
</Field>
);