primefaces / primefaces/primereact
Accessibility: Stepper component uses invalid ARIA structure (tabpanel inside tablist)
Nobody has claimed this yet.
- Dominant language
- CSS
- Stars
- 8.3k
- Forks
- 1.2k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
The Stepper component renders markup that violates ARIA structure requirements.
It assigns role="tablist" to the root container, but places elements with role="tabpanel" inside it. According to the WAI-ARIA specification, a tablist element must contain only elements with role="tab" as direct children — not tabpanel.
As a result, accessibility testing tools (e.g., axe, jest-axe, or Playwright accessibility checks) report an error such as:
aria-required-children: Element has children which are not allowed: [role=tabpanel]
Reproducer
https://stackblitz.com/edit/vitejs-vite-72fnfe5c?file=src%2FApp.tsx
System Information
System:
OS: macOS 15.7.1
Binaries:
Node: 22.19.0 - /opt/homebrew/opt/node@22/bin/node
Yarn: 1.22.19 - /opt/homebrew/bin/yarn
npm: 10.9.3 - /opt/homebrew/opt/node@22/bin/npm
Browsers:
Chrome: 141.0.7390.123
Safari: 26.0.1
npmPackages:
primereact: 10.9.7 => 10.9.7
react: ^18.3.1 => 18.3.1
tailwindcss: 3.4.3 => 3.4.3
Steps to reproduce the behavior
- Render a simple PrimeReact Stepper
- Inspect the generated DOM
- Run accessibility audit (e.g., with axe-core).
Current behavior
- The root element (.p-stepper) uses role="tablist".
- It contains child elements with role="tabpanel".
- This violates ARIA semantics and fails automated accessibility tests
Expected behavior
The DOM structure should follow ARIA guidelines.
Either:
- Use a different container role (e.g. role="group" or role="list"), or
- Move role="tabpanel" elements outside the tablist container.
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 rendering the PrimeReact Stepper and inspecting the generated .p-stepper DOM. Run an accessibility audit with axe-core, jest-axe, or Playwright, then verify that the resulting structure no longer reports aria-required-children for a tablist containing tabpanel elements.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react
- Domain
- accessibility, frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 52/100