Skip to content

Docs: explain how to fill the ... placeholders for accessible names - #43078

Merged
julien-deramond merged 1 commit into
v5-devfrom
v5-jd-accessible-name-placeholders
Oct 14, 2026
Merged

julien-deramond merged 1 commit into
v5-devfrom
v5-jd-accessible-name-placeholders

Conversation

@julien-deramond

@julien-deramond julien-deramond commented Oct 14, 2026 •

Copy link
Copy Markdown
Member

#42708 replaced the aria-label="..." of the checks and radios "Without labels" example with "Checkbox without label" and "Radio button without label". The ... is on purpose. It's how the docs mark a value that depends on your project, and copied markup with ... shows that something still has to be filled in. A name like "Checkbox without label" tends to ship as is, and it isn't a good name either: screen readers already announce the role, and it doesn't say what the control does.

That PR did point at a real gap. The sentence above the example asked for an accessible name but didn't say how to choose it. It now says the name should describe what the control does, gives aria-label="Select all rows" as an example, and says it replaces the ... placeholder. The pagination page already does this with "Search results pages".

The images page gets the same kind of sentence for alt: describe the image, or use an empty alt="" when it's only decorative. The <picture> example there uses alt="...", and so does the code of every image example, since the Example shortcode turns the placeholder SVGs into <img src="..." alt="...">. The page never said what goes there.

The other ... placeholders stay as they are. Pagination already explains its aria-label, the icon link page asks for "an appropriate aria-label", and the modal and offcanvas aria-labelledby="..." already say they reference the title. In the toasts and placeholders examples, the image isn't what the example is about.

The v6 counterpart is #43079.

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@julien-deramond julien-deramond added docs Documentation site and its content accessibility Keyboard, screen readers, contrast, ARIA v5 v5, the v5-dev branch labels Oct 14, 2026
@github-project-automation github-project-automation Bot moved this to Needs review in v5.4.0 Oct 14, 2026
@julien-deramond
julien-deramond marked this pull request as ready for review October 14, 2026 16:25
@julien-deramond
julien-deramond merged commit b8d022a into v5-dev Oct 14, 2026
7 of 8 checks passed
@julien-deramond
julien-deramond deleted the v5-jd-accessible-name-placeholders branch October 14, 2026 16:26
@github-project-automation github-project-automation Bot moved this from Needs review to Done in v5.4.0 Oct 14, 2026
@mdo mdo removed this from v5.4.0 Nov 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

accessibility Keyboard, screen readers, contrast, ARIA docs Documentation site and its content v5 v5, the v5-dev branch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant