Redocly / Redocly/redoc

fix(a11y): improve keyboard navigation and screen reader support in JSON viewer, search box, and select elements

Open
#2,799 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Bug
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:

  1. JSON Viewer Collapsers: These buttons do not announce their expanded/collapsed state via aria-expanded, and they lack descriptive dynamic aria-labels. Previously, they also couldn't be toggled via keyboard (Enter/Space).
  2. Search Box Clear Button (×): The clear icon is not focusable (tabIndex={0} is missing) and lacks keyboard interaction or an accessible role="button".
  3. SelectOnClick Wrapper (Select all text): The clickable wrapper is not focusable via keyboard, has no accessible description/role, and cannot be activated via keyboard.
  4. Search Result List: Lacks semantic grouping structure (like role="menu" or role="listbox") and has no dynamic aria-label informing 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" or role="menu").
  • Interactive states (like expanding/collapsing nodes in the JSON Viewer) should dynamically announce updates using aria-expanded="true/false" and descriptive aria-labels.
  • All elements click-toggled by mouse should also be activated via Enter or Space keys.
  • The search input results should announce results count dynamically (e.g. via aria-live or 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.