Skip to content

fix(a11y): accessible names for Checkbox and Switch - #1298

Draft
chad-agent wants to merge 7 commits into
ClickHouse:mainfrom
chad-agent:chad/2026-11-06-checkbox-names
Draft

chad-agent wants to merge 7 commits into
ClickHouse:mainfrom
chad-agent:chad/2026-11-06-checkbox-names

Conversation

@chad-agent

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

Copy link
Copy Markdown

TL;DR

Screen readers now say the right name for checkboxes and switches.

  • A label written in JSX used to come out as "[object Object]". Now it comes out as the text you see.
  • The checkboxes inside Table and CheckboxMultiSelect get names too.
  • Nothing looks different. A checkbox or switch with no label now has no name, so apps must give it one.

Description

  • Checkbox and Switch take their name from <label for>. Before, a JSX label read "[object Object]". The check icon has aria-hidden.
  • Table names its row and select-all checkboxes "Select row" and "Select all rows". The mobile select-all keeps "Select All".
  • CheckboxMultiSelect names each item checkbox by its option label. The option description becomes the checkbox description.

Links and tickets

Part of the split of #1189. Replaces #1295.

Good to know

Checklist

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

Not breaking: no prop, type or export changes. The changeset says what to check after you upgrade.

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.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, the mobile select-all keeps "Select All", and a labelled checked checkbox keeps its label.
  • The full pre-PR chain from AGENTS.md section 2 passes (876 unit tests). eslint-suppressions.json did not change.
  • Visual tests for Checkbox, Switch, Table and CheckboxMultiSelect: 126 passed, no snapshot changed or regenerated. 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. This PR adds no violation compared with main.

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 and Switch stories? The name there comes from <label for> on the Radix <button role="checkbox"> (or switch). 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 5 commits November 6, 2026 14:12
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 checkbox had no label, so Checkbox named it "undefined". It now points aria-labelledby at the option label text only, so the item icon stays out of the name, and the option description becomes its aria-describedby (APG Checkbox; WCAG 2.2 SC 4.1.2). This comes before the Checkbox change, which removes the "undefined" name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Checkbox copied `label` into `aria-label`, which gave "[object Object]" for a JSX label and "undefined" for no label. The `<label for>` now names the control, and a consumer aria-label or aria-labelledby still wins. The check icon is hidden, so a checkbox with no label is not named "check" or "minus". The NoLabel story gets an aria-label (WCAG 2.2 SC 1.1.1, 4.1.2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Switch copied `label` into `aria-label`, which gave "[object Object]" for a JSX label and "undefined" for no label. The `<label for>` now names the control, and a consumer aria-label or aria-labelledby still wins. Adds Switch.test.tsx, which did not exist. The NoLabel story gets an aria-label (WCAG 2.2 SC 4.1.2).

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

changeset-bot Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 6663b66

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

@XOP XOP added enhancement New feature or request a11y Accessibility improvements labels Nov 6, 2026
chad-agent and others added 2 commits November 9, 2026 11:36
…eaking

No component, prop, export or type changes, so app code keeps working. The changeset drops **Breaking:** and its migration list becomes "What to check after you upgrade". It also says that DOM snapshots with these controls change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@workflow-authentication-public

Copy link
Copy Markdown
Contributor

Chromatic Storybook

Check Status Link
Storybook ✅ 670 stories published Open Storybook
UI Tests ✅ 670 tests unchanged Open build

Built from commit: 6663b66c3bb370e99a7b15595dda4e5bd50eedd8 · Chromatic run

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

a11y Accessibility improvements enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants