fix(a11y): improve keyboard navigation and screen reader support in JSON viewer, search box, and select elements
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 25.9k
- Forks
- 2.4k
- Avg merge
- 13h 10m
- Merged PRs (30d)
- 4
Description
Describe the bug
Several interactive elements throughout the Redoc UI are not fully accessible for keyboard-only users or users utilizing assistive technologies (like screen readers). Specifically:
- JSON Viewer Collapsers: These buttons do not announce their expanded/collapsed state via
aria-expanded, and they lack descriptive dynamicaria-labels. Previously, they also couldn't be toggled via keyboard (Enter/Space). - Search Box Clear Button (
×): The clear icon is not focusable (tabIndex={0}is missing) and lacks keyboard interaction or an accessiblerole="button". - SelectOnClick Wrapper (
Select all text): The clickable wrapper is not focusable via keyboard, has no accessible description/role, and cannot be activated via keyboard. - Search Result List: Lacks semantic grouping structure (like
role="menu"orrole="listbox") and has no dynamicaria-labelinforming screen reader users of how many search results were returned.
Expected behavior
- Interactive elements should have
tabIndex={0}and appropriate semantic ARIA roles (e.g.role="button"orrole="menu"). - Interactive states (like expanding/collapsing nodes in the JSON Viewer) should dynamically announce updates using
aria-expanded="true/false"and descriptivearia-labels. - All elements click-toggled by mouse should also be activated via
EnterorSpacekeys. - The search input results should announce results count dynamically (e.g. via
aria-liveor proper labeling).
Minimal reproducible OpenAPI snippet (if possible)
Any OpenAPI spec containing JSON schema examples or a search box (e.g. the standard Petstore OpenAPI spec) displays these missing accessibility tags in the generated HTML.
Screenshots
(N/A - Structural HTML/A11y markup issue. You can inspect the DOM in the DevTools console to see the elements before the changes)
Additional context
Improving accessibility ensures compliance with modern web standard guidelines (WCAG 2.1 AA) and makes Redoc documentation usable for a wider range of users, including those relying on screen readers or keyboard navigation.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by inspecting the JSON Viewer collapsers, search box clear button, SelectOnClick wrapper, and search result list in a Redoc UI using the standard Petstore OpenAPI spec. Verify keyboard activation and the expected ARIA roles, labels, expanded state, focusability, and result-count announcement; done when these behaviors are observable in the generated HTML and work for keyboard and screen-reader users.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- accessibility, frontend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100