Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com> Co-authored-by: Harry Whorlow <whorlowharry@gmail.com> Co-authored-by: Harry Whorlow <79278353+harry-whorlow@users.noreply.github.com> Co-authored-by: Lachlan Collins <1667261+lachlancollins@users.noreply.github.com>
4.7 KiB
| title | id |
|---|---|
| Accessibility Plugin | a11y-plugin |
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