primefaces / primefaces/primereact

Accessibility: Stepper component uses invalid ARIA structure (tabpanel inside tablist)

Open
#8,358 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Component: Accessibility
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
  1. Render a simple PrimeReact Stepper
  2. Inspect the generated DOM
  3. 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".
Image
  • This violates ARIA semantics and fails automated accessibility tests
Image
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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.