The TanStack Devtools Accessibility (A11y) Plugin provides real-time accessibility auditing for your web applications, powered by axe-core. It helps you identify and fix accessibility issues during development.
Features#
- Full Page Scanning - Audit your entire page for accessibility violations
- Component-Level Scanning - Scope audits to specific components using React hooks
- Visual Overlays - Highlight problematic elements with severity-based colors
- Click-to-Navigate - Click on an issue to automatically scroll to and highlight the element
- Dark Mode Support - Automatically adapts to the devtools theme
- Devtools-Aware - Automatically excludes devtools panels from scanning
- Configurable Rule Sets - Support for WCAG 2.0/2.1/2.2 (A/AA/AAA), Section 508, and best practices
- Export Reports - Download results as JSON or CSV
- Persistent Settings - Configuration saved to localStorage
Installation#
npm install @tanstack/devtools-a11y
# or
pnpm add @tanstack/devtools-a11y
# or
yarn add @tanstack/devtools-a11y
Quick Start (React)#
import { createRoot } from 'react-dom/client'
import { TanStackDevtools } from '@tanstack/react-devtools'
import { a11yDevtoolsPlugin } from '@tanstack/devtools-a11y/react'
createRoot(document.getElementById('root')!).render(
<>
<App />
<TanStackDevtools plugins={[a11yDevtoolsPlugin()]} />
</>,
)
Quick Start (Solid)#
import { render } from 'solid-js/web'
import { TanStackDevtools } from '@tanstack/solid-devtools'
import { a11yDevtoolsPlugin } from '@tanstack/devtools-a11y/solid'
render(
() => (
<>
<App />
<TanStackDevtools plugins={[a11yDevtoolsPlugin()]} />
</>
),
document.getElementById('root')!,
)
Quick Start (Vue)#
import { createA11yDevtoolsVuePlugin } from '@tanstack/devtools-a11y/vue'
const plugins = [createA11yDevtoolsVuePlugin()]
Click-to-Navigate#
When you click on an issue in the panel, the plugin will:
- Scroll the problematic element into view (centered in the viewport)
- Highlight the element with a pulsing overlay matching its severity color
- Show a tooltip with the rule ID and impact level
This makes it easy to locate and inspect issues directly on the page.
Panel Configuration#
Initial configuration can be provided via the vanilla plugin API:
import { createA11yPlugin } from '@tanstack/devtools-a11y'
const plugin = createA11yPlugin({
threshold: 'serious',
ruleSet: 'wcag21aa',
showOverlays: true,
persistSettings: true,
disabledRules: [],
})
Common options fields:
threshold: minimum impact level to showruleSet: rule preset ('wcag2a' | 'wcag2aa' | 'wcag21aa' | 'wcag22aa' | 'section508' | 'best-practice' | 'all')showOverlays: highlight issues in the pagepersistSettings: store config in localStoragedisabledRules: rule IDs to ignore
If you don't need to provide initial configuration, you can use the framework plugin helpers directly (the settings UI persists changes to localStorage by default).
Severity Levels#
Issues are categorized by impact level with corresponding overlay colors:
| Impact | Color | Description |
|---|---|---|
| Critical | Red | Must be fixed - prevents users from accessing content |
| Serious | Orange | Should be fixed - significantly impacts user experience |
| Moderate | Yellow | Consider fixing - affects some users |
| Minor | Blue | Optional improvement - minor impact |
Framework Support#
The panel UI is implemented in Solid and wrapped for React, Solid, Preact, and Vue
using @tanstack/devtools-utils.
Export Formats#
JSON Export#
import { exportToJSON } from '@tanstack/devtools-a11y'
const jsonString = exportToJSON(auditResult)
CSV Export#
import { exportToCSV } from '@tanstack/devtools-a11y'
const csvString = exportToCSV(auditResult)
Supported Standards#
The plugin supports the following accessibility standards:
- WCAG 2.0 Level A, AA, AAA
- WCAG 2.1 Level A, AA, AAA
- WCAG 2.2 Level AA
- Section 508
- Best Practices (non-standard recommendations)
Troubleshooting#
Issues not appearing#
- Check that the element is visible in the viewport
- Ensure the element is not excluded by
excludeSelectors - Verify the selected standard includes the relevant rule
Overlays not showing#
- Confirm overlays are enabled in the panel settings
- Check for CSS conflicts with
z-indexorpointer-events - Ensure the container element exists in the DOM
Example#
See the full working example at:
examples/react/a11y-devtools/
Run it with:
cd examples/react/a11y-devtools
pnpm dev