Skip to content

fix(a11y): accessible names for Tier 1 form controls, Select and Link - #1295

Closed
chad-agent wants to merge 19 commits into
ClickHouse:mainfrom
chad-agent:chad/2026-11-05-tier1-names
Closed

chad-agent wants to merge 19 commits into
ClickHouse:mainfrom
chad-agent:chad/2026-11-05-tier1-names

Conversation

@chad-agent

@chad-agent chad-agent commented Nov 5, 2026 •

Copy link
Copy Markdown

Description

Form controls, Select and Link now give screen readers the right names. This is the first of the smaller PRs that split up #1189, and it follows the approach of #1189 for these components.

  • Checkbox, Switch and RadioGroup.Item take their name from the visible label. They no longer copy label into aria-label, which gave "[object Object]" for a JSX label and "undefined" for no label (WCAG 2.2 SC 4.1.2 Name, Role, Value; AGENTS.md section 7).
  • RadioGroup is named by its label through aria-labelledby. Before, <label htmlFor> pointed at the div role="radiogroup", which a label cannot name (SC 1.3.1 Info and Relationships, 4.1.2). A wrapper that passes aria-labelledby={undefined} keeps that name.
  • aria-label, aria-labelledby and aria-describedby on RadioGroup.Item now reach the radio, not the wrapper div.
  • aria-label and aria-labelledby on Select now name the trigger button. triggerProps still win. This covers MultiSelect and CheckboxMultiSelect too.
  • The Select search input is named "Search options" (SC 4.1.2), and its clear button "Clear search" instead of "cross" (SC 2.4.6 Headings and Labels).
  • Decorative icons stop reading out their icon names: the Checkbox check icon, the Select sort and check icons, and the Link icon when the link has text (SC 1.1.1 Non-text Content). An icon-only Link keeps the icon name, as on main (SC 2.4.4 Link Purpose (In Context)). The TextField loading icon is named "Loading".
  • Three places inside click-ui render a Checkbox without a label. They were named "undefined" and would have had no name after this change, so they get names in the same PR: the Table row checkbox ("Select row"), the Table header select-all ("Select all rows") and the CheckboxMultiSelect item checkbox. The item checkbox is named by the option label only. The option description, or a CheckboxMultiSelect.ItemDescription child, becomes its description (aria-describedby), as in the APG Checkbox pattern.

How to review

Each commit is one change with its own tests, so you can review them one at a time.

First round:

  1. fix(Table): name the row and header select-all checkboxes. The mobile select-all keeps its visible label "Select All".
  2. fix(Select): point each CheckboxMultiSelect item checkbox at its label with aria-labelledby.
  3. fix(Checkbox): remove the stringified aria-label.
  4. fix(Switch): the same, plus a new Switch.test.tsx (none existed).
  5. fix(RadioGroup): name the group with aria-labelledby, and pass the item aria-* props to the radio.
  6. fix(Select): route aria-label/aria-labelledby to the trigger, name the search input and clear button, hide the sort and check icons.
  7. fix(Link): hide the icon.
  8. fix(TextField): name the loading icon.
  9. The changeset.

Commits 1 and 2 come first so that no internal checkbox loses its name when commit 3 lands.

Fix round, after a review of the first round:

  1. fix(Checkbox): hide the check icon. Without it, a checkbox with no label was named "check" when checked and "minus" when indeterminate.
  2. fix(Select): name the CheckboxMultiSelect item checkbox by the label text only. Commit 2 pointed at the whole item, so the name also held the icon name and the description ("Alpha user", "Beta Second letter").
  3. fix(Link): hide the icon only when the link has text. Commit 7 left an icon-only link with no name.
  4. fix(RadioGroup): read the consumer aria-label and aria-labelledby before the spread, so aria-labelledby={undefined} keeps the group name.
  5. docs(Checkbox, Switch): add an aria-label to the two NoLabel stories, which now render controls with no name.
  6. The changeset, now marked Breaking: with a migration note (AGENTS.md section 9).

Round 3, after a second review:

  1. fix(Select): describe the CheckboxMultiSelect item checkbox by its ItemDescription children. In the children form, which the OptionsAsChildren story uses, the description sat inside the label, so the name was "Content3 Description of Content3" and there was no description. aria-describedby is now set only for a description that renders. This adds a small helper, hasRenderableContent.
  2. fix(Link): hide the icon only when the children render something. children={[]} gave no name, and children={0} gave "0 popout".
  3. fix(RadioGroup): treat aria-labelledby="" as not set, so the group keeps the name "Plan".
  4. The changeset: the description line covers ItemDescription children, and the migration note puts a visible label first.

Accessible names before and after, computed with dom-accessibility-api in jsdom. The Table and CheckboxMultiSelect rows come from the unit tests in this PR.

Control main This branch
Checkbox, JSX label "Accept terms" "[object Object]" "Accept terms"
Checkbox, no label, unchecked, checked or indeterminate "undefined" none, and no aria-label
Switch, JSX label "Dark mode" "[object Object]" "Dark mode"
Switch, no label "undefined" none, and no aria-label
RadioGroup, label "Plan", with or without id none "Plan"
RadioGroup, label "Plan", aria-labelledby={undefined} none "Plan"
RadioGroup, label "Plan", aria-labelledby="" none "Plan"
Radio, JSX label "Pro" "[object Object]" "Pro"
Radio, no label "undefined" none, and no aria-label
Radio with aria-label="Consumer name" "Basic" (attribute on the wrapper div) "Consumer name"
Select with aria-label="Fruit" "Select an option sort" "Fruit"
Select search input none "Search options"
Select search clear button "cross" "Clear search"
Link "Docs" with icon="arrow-right" "Docs arrow-right" "Docs"
Link with only icon="popout" "popout" "popout"
Link with icon="popout" and children={[]} "popout" "popout"
Link with icon="popout" and children={0} "0 popout" "0"
TextField loading icon "loading-animated" "Loading"
Table row checkbox "undefined" "Select row"
Table header select-all checkbox "undefined" "Select all rows"
CheckboxMultiSelect item "Alpha" with icon: 'user' "undefined" "Alpha"
CheckboxMultiSelect item "Beta" with description "Second letter" "undefined" "Beta", description "Second letter"
CheckboxMultiSelect item "Content3" with an ItemDescription child "undefined" "Content3", description "Description of Content3"
CheckboxMultiSelect item "Gamma" with description 0 "undefined" "Gamma", description "0"

These stay the same: Icon default "check", IconButton without aria-label "dots-vertical", Button with an icon and a label "Add", TextField label "Name", TextField clear button "clear input".

Links and tickets

Part of the split of #1189.

Good to know

No public prop changes and no visual change. Some things a consumer can observe do change, so the changeset is marked Breaking: and has a migration note:

  • Checkbox, Switch and RadioGroup.Item no longer set aria-label from label. A control with a string label keeps the same name. A control with no label goes from "undefined" to no name, so it needs a visible label, or aria-labelledby that points at visible text. aria-label fits only when the purpose is already visible from context, such as a checkbox in a table row (SC 3.3.2 Labels or Instructions). axe flags a missing name, but it did not flag "undefined".
  • aria-label and aria-labelledby on a Select move from the wrapper div to the trigger button, so getByLabelText now returns the button.
  • Some names get shorter: a Select trigger loses " sort", and a Link with text loses its icon name. Tests that query those names need the new name.

This PR may need a rebase if #1291 (focus ring CSS for Checkbox, Switch and RadioGroup) or #1293 (vitest bump that edits some of the same test files) lands first.

Things I noticed and did not change, to keep this PR to names:

  • Icon is named by its icon name by default (role="img"). Each decorative use needs aria-hidden by hand, as in this PR. Making Icon decorative by default is a separate change.
  • "Select row" is the same on every row. A name per row is a design question for a later Table PR.
  • The new names are English strings. click-ui has no i18n mechanism yet; this follows the existing "clear input".
  • The Select trigger does not expose the selected value, and options have no role. With an aria-label, the trigger name is that label without the value. That is the combobox/listbox pattern work (APG Combobox, Listbox), not a naming fix.
  • CheckboxMultiSelect puts a focusable checkbox inside each option (nested interactive control).
  • IconButton without aria-label falls back to the icon name. 13 call sites outside these components.
  • Field errors are not linked with aria-describedby and aria-invalid. fix(A11Y): Low hanging fruit, aria labels #1189 also adds role="alert", which is a live region, so it needs a maintainer decision first (AGENTS.md section 7).
  • RadioGroup.Item still puts its other rest props (data-testid, handlers) on the wrapper div. Select still puts a consumer aria-describedby on the wrapper.
  • A CheckboxMultiSelect.ItemDescription child gets an internal id, which replaces an id the consumer set on it. An ItemDescription inside a fragment or another element is not found, so it stays part of the name.
  • Link counts an empty fragment (<></>) as content, so an icon with only that as children is hidden. An element that renders null is the same, and neither can be detected at render time.
  • axe reports these on main and on this branch alike: link text #437eef on #ffffff is 3.83:1 in the light theme (SC 1.4.3 Contrast (Minimum) needs 4.5:1); the open CheckboxMultiSelect popover has role="dialog" with no name; and the Radix popover sets aria-hidden on the page behind it while the trigger there stays focusable (axe aria-hidden-focus).
  • feat(Table): make table-layout: auto the default #683 also changes Table.tsx. My two lines there are small, so a conflict is easy to resolve.

Checklist

  • Breaking changes? (add migration notes in changesets)
  • Visual changes? (specify in changesets)
  • Design review needed?

Breaking is ticked because default names change and some aria-* props land on a different element, so a consumer test can fail. No props were removed or renamed. The changeset is a breaking minor with a migration note.

Contribution

  • Sufficient research before PR
  • Self-reviewed the PR
  • Manually tested the changes (when applies - visual confirmation in Storybook)
  • build and build-storybook work locally
  • Tests and Stories are aligned with the changes

Not done: a manual check in Storybook. The only story change is an aria-label on the two NoLabel stories.

Accessibility

  • Keyboard - every action works with Tab / Enter / Space / Esc; focus is visible and returns to the trigger on close
  • Names — every control has a name that includes its visible label; icon-only controls take aria-label
  • Vision — colors come from tokens, focus ring shows, targets are at least 24×24 px

Names is ticked for the controls in this PR only. Keyboard and Vision are not ticked because this PR does not change them, and I did not re-test them.

WCAG 2.2 criteria checked: 1.1.1 Non-text Content, 1.3.1 Info and Relationships, 2.4.4 Link Purpose (In Context), 2.4.6 Headings and Labels, 2.5.3 Label in Name, 4.1.2 Name, Role, Value.

Tested:

  • Unit tests query by role and name (getByRole(role, { name })). Each test for a fixed defect failed before its fix and passes after it. A few tests guard behavior that must not change: a consumer aria-label or aria-labelledby still wins, triggerProps still win, the mobile select-all keeps "Select All", a labelled checked checkbox keeps its label, and a children item with no ItemDescription gets no aria-describedby.
  • Mutation check: inverting the RadioGroup aria-label condition, or moving the trigger aria-label after triggerProps, makes tests fail.
  • The full pre-PR chain from AGENTS.md section 2 passes (909 unit tests at round 3), plus build:health_check in the first round. eslint-suppressions.json did not change.
  • Visual tests, no snapshot changed or regenerated. First round: Checkbox, Switch, RadioGroup, Select, MultiSelect, CheckboxMultiSelect, Link, TextField and Table, 217 passed. Fix round: the seven components it touches, 128 passed. Round 3: Select, MultiSelect, CheckboxMultiSelect, Link and RadioGroup, 79 passed. No visual spec renders the ItemDescription children form, so I also compared screenshots of the open OptionsAsChildren story before and after commit 16, in both themes: 0 pixels differ. yarn test:visual cannot build its image locally right now, because Node 26 in mcr.microsoft.com/playwright:v1.64.1-noble no longer ships corepack. So I ran the same specs in that image directly, with CI=true.
  • axe-core from node_modules, default rules, on the static Storybook build: all 58 stories of Checkbox, Switch, RadioGroup, CheckboxMultiSelect (menu open) and Link, on this branch and on main. This PR adds no violation. It removes one: the unnamed search input in the open CheckboxMultiSelect. Round 3 gives the same result on every story. The older violations are listed under "Things I noticed".

Not tested:

  • A screen reader pass (NVDA, JAWS, VoiceOver).
  • A check in the browser accessibility inspector. Reviewer, could you spend 5 minutes in the Chrome accessibility inspector on the Checkbox, Switch and RadioGroup stories? The name there comes from <label for> on the Radix <button role="checkbox"> (or switch, radio). HTML lists button as labelable and Radix documents this pattern, but jsdom is the only engine I checked it in.
  • A manual keyboard pass. Keyboard behavior did not change.

Screenshots

No visual change. The visual tests above pass without new snapshots.

🤖 Generated with Claude Code

chad-agent and others added 9 commits November 5, 2026 15:33
The row checkbox and the header select-all checkbox render a Checkbox
without a label, so their accessible name was the string "undefined".
Name them "Select row" and "Select all rows" (WCAG 2.2 SC 4.1.2).

The mobile select-all checkbox keeps its visible label "Select All" as
its name; a test guards it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each CheckboxMultiSelect item renders a Checkbox without a label, so its
accessible name was the string "undefined". Point the checkbox at the
item's label text with aria-labelledby (WCAG 2.2 SC 4.1.2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Checkbox stringified its `label` prop into `aria-label`. A JSX label gave
the name "[object Object]" and no label gave "undefined". The label is
already wired with <label htmlFor>, so drop the aria-label and let the
visible label name the control (WCAG 2.2 SC 4.1.2, 2.5.3).

A consumer aria-label or aria-labelledby still wins. A Checkbox with no
label now has no name instead of "undefined" and needs an aria-label.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Switch stringified its `label` prop into `aria-label`, the same defect as
Checkbox: "[object Object]" for a JSX label, "undefined" without one.
Drop the aria-label; the visible label already names the switch through
<label htmlFor> (WCAG 2.2 SC 4.1.2, 2.5.3).

Add Switch.test.tsx (none existed) with a click test and the name cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The group label used <label htmlFor> on the Radix root, a div with
role="radiogroup" that a label cannot name, so the group had no name.
Link the label with aria-labelledby instead (WCAG 2.2 SC 1.3.1, 4.1.2).
A consumer aria-label or aria-labelledby on the group still wins.

RadioGroup.Item stringified its label into aria-label ("[object Object]"
for a JSX label, "undefined" without one) and left a consumer aria-label
or aria-describedby on the wrapper div. Drop the stringified value and
pass aria-label, aria-labelledby and aria-describedby to the radio.
Other rest props stay on the wrapper as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An aria-label or aria-labelledby passed to Select landed on the wrapper
div (and on the "no options" container), so the trigger kept the name
"Select an option sort". Route both to the trigger button; triggerProps
still win (WCAG 2.2 SC 4.1.2).

Name the search input "Search options" (SC 4.1.2, 3.3.2) and its clear
button "Clear search" instead of the icon name "cross" (SC 2.4.6).
Hide the decorative sort and option check icons, which exposed their
icon names (SC 1.1.1).

This also covers MultiSelect and CheckboxMultiSelect, which share the
same internal Select.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Link icon rendered as an image named by its icon name, so a link
"Docs" with icon="arrow-right" was announced as "Docs arrow-right".
Mark the icon aria-hidden; the link text names the link (WCAG 2.2
SC 1.1.1). The icon's data-testid stays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The loading icon rendered as an image named "loading-animated", its icon
name. Name it "Loading" (WCAG 2.2 SC 1.1.1). The clear button keeps its
name "clear input".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@changeset-bot

changeset-bot Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 137da59

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@clickhouse/click-ui Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@workflow-authentication-public

Copy link
Copy Markdown
Contributor

Chromatic Storybook

Check Status Link
Storybook ✅ 670 stories published Open Storybook
UI Tests ⏳ 49 changes must be accepted as baselines Open build

Built from commit: 5421848818e8e2af345c769b0bb7b74a4f1f7b2b · Chromatic run

Statuses as of the end of the run. The build link shows the live review state.

@XOP XOP added bug Something isn't working a11y Accessibility improvements labels Nov 5, 2026
chad-agent and others added 10 commits November 5, 2026 16:25
A Checkbox without a label took its name from the indicator icon, so it
was announced as "check" when checked and "minus" when indeterminate.
The icon is decorative; the checked state is already exposed by the
checkbox role. WCAG 2.2 SC 1.1.1, 4.1.2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The item checkbox pointed aria-labelledby at the whole icon wrapper, so
its name also held the icon name and the option description, for
example "Alpha user" or "Beta Second letter". It now points at the
label text only, and the description is wired with aria-describedby,
as the APG Checkbox pattern does. WCAG 2.2 SC 1.1.1, 4.1.2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Hiding the icon in every case left an icon-only Link with no name. The
icon is now hidden only when the link has text, so an icon-only link is
named by the icon, as before this change. WCAG 2.2 SC 2.4.4, 4.1.2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The group set its own aria-labelledby before spreading the rest props,
so a wrapper that forwarded aria-labelledby={undefined} erased the name
taken from the label. The consumer values are now read first and the
label is used only when neither aria-label nor aria-labelledby is set.
WCAG 2.2 SC 1.3.1, 4.1.2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Without a visible label these stories now render controls with no
accessible name, which the Storybook accessibility panel reports. They
now show the documented way to name such a control: aria-label.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Default names change for unlabelled controls and aria-* props land on
a different element, so a consumer test can fail. The changeset now
follows the Breaking and Migration format and lists every observable
change: MultiSelect and CheckboxMultiSelect, the hidden option check
icon, the renamed clear button and loading icon.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ption children

In the children form, a CheckboxMultiSelect.ItemDescription child sat inside
the span that names the checkbox, so the description became part of the name
("Content3 Description of Content3") and the checkbox had no description.
ItemDescription children now render after the label span, and the checkbox
points aria-describedby at them (APG Checkbox; WCAG 2.2 SC 1.3.1).

aria-describedby is now set only for a description that is rendered. A
`label: ''` with a description no longer points at a missing id, and a
`description` of 0 is now used.

Adds hasRenderableContent, which tells a node that renders something (a
number, non-blank text or an element) from one that renders nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The icon was hidden whenever `children` was truthy. `children={[]}` hid the
only name source, so the link had no name (WCAG 2.2 SC 2.4.4, 4.1.2), and
`children={0}` exposed the icon slug, giving "0 popout" (SC 1.1.1). The icon
is now hidden only when the children render a number, non-blank text or an
element.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`??` kept `aria-labelledby=""`, which wrappers often pass when they join an
empty id list. An empty value points at nothing, so the group lost its
visible label name "Plan" (WCAG 2.2 SC 1.3.1, 4.1.2). An empty
aria-labelledby now falls back to the label, as an empty aria-label already
did.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The description line now covers the ItemDescription children form, which
round 3 wires to aria-describedby. The Migration step puts a visible label
first: an aria-label is not visible, so on its own it does not meet WCAG 2.2
SC 3.3.2. aria-label stays as the option for a purpose already visible from
context.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chad-agent

Copy link
Copy Markdown
Author

Replaced by #1298, which keeps only Checkbox and Switch and the checkboxes that use them. The other changes here follow in smaller PRs.

@XOP XOP added invalid This doesn't seem right and removed bug Something isn't working a11y Accessibility improvements labels Nov 6, 2026
@XOP XOP closed this Nov 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

invalid This doesn't seem right

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants