Skip to content

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

TypeScript

fix(radiolist): label the group via aria-labelledby, drop orphaned htmlFor (forms-14) (#3453)

Cindy Zhanga8eb271eebaa
diff --git a/.changeset/radiolist-label-association.md b/.changeset/radiolist-label-association.md
new file mode 100644
index 0000000000..c6758eb571
--- /dev/null
+++ b/.changeset/radiolist-label-association.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] RadioList: the group is now named via `aria-labelledby` pointing at the field label element, and the label no longer carries an orphaned `htmlFor` (it pointed at an id no radio used, so clicking it did nothing and the group was double-labeled). `Field`/`FieldLabel` gain optional `labelID` and `isGroupLabel` props to support grouping controls (#3343).
+@cixzhang
diff --git a/packages/core/src/Field/Field.test.tsx b/packages/core/src/Field/Field.test.tsx
index 9def555302..b7c309dc9c 100644
--- a/packages/core/src/Field/Field.test.tsx
+++ b/packages/core/src/Field/Field.test.tsx
@@ -93,6 +93,38 @@ describe('Field', () => {
expect(label).toBeVisible();
});
+ it('renders a single-control label as a <label> with htmlFor', () => {
+ render(
+ <Field label="Email" inputID="email-input">
+ <input id="email-input" />
+ </Field>,
+ );
+ const labelEl = screen.getByText('Email');
+ expect(labelEl.tagName).toBe('LABEL');
+ expect(labelEl).toHaveAttribute('for', 'email-input');
+ });
+
+ it('renders a group label as a <span> (not <label>) with no htmlFor', () => {
+ render(
+ <Field
+ label="Plan"
+ inputID="plan-group"
+ labelElementID="plan-label"
+ isGroupLabel>
+ <div role="radiogroup" aria-labelledby="plan-label" />
+ </Field>,
+ );
+ const labelEl = screen.getByText('Plan');
+ // A group's accessible-name element must not be a literal <label>.
+ expect(labelEl.tagName).toBe('SPAN');
+ expect(labelEl.closest('label')).toBeNull();
+ expect(labelEl).not.toHaveAttribute('for');
+ // labelElementID is applied to the label element and referenced by the group.
+ expect(labelEl).toHaveAttribute('id', 'plan-label');
+ const group = screen.getByRole('radiogroup', {name: 'Plan'});
+ expect(group.getAttribute('aria-labelledby')).toBe(labelEl.id);
+ });
+
it('forwards ref correctly', () => {
const ref = vi.fn();
render(
diff --git a/packages/core/src/Field/Field.tsx b/packages/core/src/Field/Field.tsx
index 368f5c8728..5247b3bced 100644
--- a/packages/core/src/Field/Field.tsx
+++ b/packages/core/src/Field/Field.tsx
@@ -99,9 +99,26 @@ export interface FieldProps extends Omit<
*/
description?: string;
/**
- * ID for the input element (used for label's htmlFor attribute).
+ * ID of the input element this label points AT (used as the label's
+ * `htmlFor`). This is the id of the *control*, not of the label element —
+ * see `labelElementID` for the latter.
*/
inputID: string;
+ /**
+ * The `id` applied TO the label element itself (distinct from `inputID`,
+ * which is the control the label points at). A grouping control
+ * (radiogroup, checkbox group) references this via `aria-labelledby` to take
+ * the label as its accessible name. Pair with `isGroupLabel`.
+ */
+ labelElementID?: string;
+ /**
+ * When the field wraps a group of controls rather than a single input, set
+ * this so the label renders as a non-`<label>` element (a `<span>`): a
+ * `<label>` semantically names one control and can't be associated with a
+ * group. Pair with `labelElementID` + `aria-labelledby` on the group.
+ * @default false
+ */
+ isGroupLabel?: boolean;
/**
* ID for the description element (use for aria-describedby on the input).
*/
@@ -172,6 +189,8 @@ export function Field({
isLabelHidden = false,
description,
inputID,
+ labelElementID,
+ isGroupLabel = false,
descriptionID,
isOptional = false,
isRequired = false,
@@ -206,6 +225,8 @@ export function Field({
<FieldLabel
label={label}
inputID={inputID}
+ labelElementID={labelElementID}
+ isGroupLabel={isGroupLabel}
isLabelHidden={isLabelHidden}
isDisabled={isDisabled}
isOptional={isOptional}
@@ -245,10 +266,7 @@ export function Field({
<div {...stylex.props(styles.horizontalLabelAlign)}>{labelNode}</div>
<div {...stylex.props(styles.inputStatusWrapper)}>
{description && (
- <Text
- type="supporting"
- display="block"
- id={resolvedDescriptionID}>
+ <Text type="supporting" display="block" id={resolvedDescriptionID}>
{description}
</Text>
)}
diff --git a/packages/core/src/Field/FieldLabel.tsx b/packages/core/src/Field/FieldLabel.tsx
index 49fd029492..04f776db6a 100644
--- a/packages/core/src/Field/FieldLabel.tsx
+++ b/packages/core/src/Field/FieldLabel.tsx
@@ -82,9 +82,28 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {
*/
label: string;
/**
- * ID of the input element this label is for.
+ * ID of the input element this label points AT (rendered as `htmlFor` on the
+ * label). This is *not* the id of the label element itself — see
+ * `labelElementID` for that.
*/
inputID: string;
+ /**
+ * The `id` applied TO the label element itself (not the element it points
+ * at — that's `inputID`). A grouping control (e.g. `role="radiogroup"`) can
+ * reference this via `aria-labelledby` to take the label as its accessible
+ * name.
+ */
+ labelElementID?: string;
+ /**
+ * When true, the field wraps a *group* of controls (e.g. a radiogroup)
+ * rather than a single input. In that case the label is rendered as a
+ * `<span>` instead of a `<label>` — a `<label>` semantically names one form
+ * control and can't be associated with a group, so it must not be a literal
+ * label element. The group takes the label as its name via
+ * `labelElementID` + `aria-labelledby`.
+ * @default false
+ */
+ isGroupLabel?: boolean;
/**
* Whether to visually hide the label and description (still accessible
* to screen readers). When hidden, the entire label group is rendered
@@ -142,6 +161,8 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {
export function FieldLabel({
label,
inputID,
+ labelElementID,
+ isGroupLabel = false,
isLabelHidden = false,
isDisabled = false,
isOptional = false,
@@ -154,11 +175,38 @@ export function FieldLabel({
}: FieldLabelProps) {
const statusText = isOptional ? 'Optional' : isRequired ? 'Required' : null;
+ // A group label (e.g. for a radiogroup) must not be a literal `<label>`
+ // element: a `<label>` semantically names a single form control and can't be
+ // associated with a group. Render it as a `<span>` instead, keeping all the
+ // label styling and slots. The group references it via `aria-labelledby`.
+ const LabelElement = isGroupLabel ? 'span' : 'label';
+
+ const labelContent = (
+ <>
+ {labelIcon && renderIconSlot(labelIcon, {size: 'sm', color: 'inherit'})}
+ {label}
+ {statusText && (
+ <span {...stylex.props(styles.optionalRequired)}>
+ <span aria-hidden="true"> ∙ </span>
+ {statusText}
+ </span>
+ )}
+ {labelTooltip && (
+ <Tooltip content={labelTooltip} placement="above">
+ <Icon icon="info" size="sm" color="inherit" />
+ </Tooltip>
+ )}
+ </>
+ );
+
return (
<>
- <label
+ <LabelElement
ref={ref}
- htmlFor={inputID}
+ id={labelElementID}
+ // `htmlFor` only applies to a real `<label>` associating with a single
+ // control; a group label (span) has no `htmlFor`.
+ htmlFor={isGroupLabel ? undefined : inputID}
{...mergeProps(
themeProps('field-label'),
stylex.props(
@@ -167,20 +215,8 @@ export function FieldLabel({
isLabelHidden && styles.srOnly,
),
)}>
- {labelIcon && renderIconSlot(labelIcon, {size: 'sm', color: 'inherit'})}
- {label}
- {statusText && (
- <span {...stylex.props(styles.optionalRequired)}>
- <span aria-hidden="true"> ∙ </span>
- {statusText}
- </span>
- )}
- {labelTooltip && (
- <Tooltip content={labelTooltip} placement="above">
- <Icon icon="info" size="sm" color="inherit" />
- </Tooltip>
- )}
- </label>
+ {labelContent}
+ </LabelElement>
{description && (
<span
id={descriptionID}
diff --git a/packages/core/src/RadioList/RadioList.test.tsx b/packages/core/src/RadioList/RadioList.test.tsx
index 22c6e52e6a..7e8f58987c 100644
--- a/packages/core/src/RadioList/RadioList.test.tsx
+++ b/packages/core/src/RadioList/RadioList.test.tsx
@@ -271,11 +271,32 @@ describe('RadioList', () => {
);
const label = screen.getByText('Hidden label');
expect(label).toBeInTheDocument();
- // The radiogroup should still be labeled
- expect(screen.getByRole('radiogroup')).toHaveAttribute(
- 'aria-label',
- 'Hidden label',
+ // The radiogroup is named by the label element via aria-labelledby (not a
+ // duplicated aria-label), so its accessible name is still "Hidden label".
+ expect(
+ screen.getByRole('radiogroup', {name: 'Hidden label'}),
+ ).toBeInTheDocument();
+ expect(screen.getByRole('radiogroup')).toHaveAttribute('aria-labelledby');
+ expect(screen.getByRole('radiogroup')).not.toHaveAttribute('aria-label');
+ });
+
+ it('renders the group label as a span, not a label element (forms-14)', () => {
+ render(
+ <RadioList label="Plan" value="" onChange={() => {}}>
+ <RadioListItem label="Free" value="free" />
+ <RadioListItem label="Pro" value="pro" />
+ </RadioList>,
);
+ // A radiogroup's accessible name must not come from a literal `<label>`
+ // element — a `<label>` names a single control and can't be associated
+ // with a group. It is rendered as a `<span>` and referenced via
+ // aria-labelledby (with no orphaned htmlFor).
+ const labelEl = screen.getByText('Plan');
+ expect(labelEl.tagName).toBe('SPAN');
+ expect(labelEl.closest('label')).toBeNull();
+ expect(labelEl).not.toHaveAttribute('for');
+ const group = screen.getByRole('radiogroup', {name: 'Plan'});
+ expect(group.getAttribute('aria-labelledby')).toBe(labelEl.id);
});
it('renders description on items', () => {
diff --git a/packages/core/src/RadioList/RadioList.tsx b/packages/core/src/RadioList/RadioList.tsx
index aab1b6faa1..5d864f1dfd 100644
--- a/packages/core/src/RadioList/RadioList.tsx
+++ b/packages/core/src/RadioList/RadioList.tsx
@@ -183,6 +183,7 @@ export function RadioList({
}: RadioListProps) {
const name = useId();
const inputID = useId();
+ const labelElementID = useId();
const descriptionID = useId();
const statusMessageID = useId();
@@ -283,6 +284,8 @@ export function RadioList({
isLabelHidden={isLabelHidden}
description={description}
inputID={inputID}
+ labelElementID={labelElementID}
+ isGroupLabel
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}
@@ -305,7 +308,7 @@ export function RadioList({
<div
ref={groupRef}
role="radiogroup"
- aria-label={label}
+ aria-labelledby={labelElementID}
onFocus={handleFocus}
aria-describedby={
[