Open History to see the last commit
1---
2title: Accessibility Plugin
3id: a11y-plugin
4---
5β
6The TanStack Devtools Accessibility (A11y) Plugin provides real-time accessibility auditing for your web applications, powered by [axe-core](https://github.com/dequelabs/axe-core). It helps you identify and fix accessibility issues during development.
7β
8## Features
9β
10- **Full Page Scanning** - Audit your entire page for accessibility violations
11- **Component-Level Scanning** - Scope audits to specific components using React hooks
12- **Visual Overlays** - Highlight problematic elements with severity-based colors
13- **Click-to-Navigate** - Click on an issue to automatically scroll to and highlight the element
14- **Dark Mode Support** - Automatically adapts to the devtools theme
15- **Devtools-Aware** - Automatically excludes devtools panels from scanning
16- **Configurable Rule Sets** - Support for WCAG 2.0/2.1/2.2 (A/AA/AAA), Section 508, and best practices
17- **Export Reports** - Download results as JSON or CSV
18- **Persistent Settings** - Configuration saved to localStorage
19β
20## Installation
21β
22```bash
23npm install @tanstack/devtools-a11y
24# or
25pnpm add @tanstack/devtools-a11y
26# or
27yarn add @tanstack/devtools-a11y
28```
29β
30## Quick Start (React)
31β
32```tsx
33import { createRoot } from 'react-dom/client'
34import { TanStackDevtools } from '@tanstack/react-devtools'
35import { a11yDevtoolsPlugin } from '@tanstack/devtools-a11y/react'
36β
37createRoot(document.getElementById('root')!).render(
38 <>
39 <App />
40 <TanStackDevtools plugins={[a11yDevtoolsPlugin()]} />
41 </>,
42)
43```
44β
45## Quick Start (Solid)
46β
47```tsx
48import { render } from 'solid-js/web'
49import { TanStackDevtools } from '@tanstack/solid-devtools'
50import { a11yDevtoolsPlugin } from '@tanstack/devtools-a11y/solid'
51β
52render(
53 () => (
54 <>
55 <App />
56 <TanStackDevtools plugins={[a11yDevtoolsPlugin()]} />
57 </>
58 ),
59 document.getElementById('root')!,
60)
61```
62β
63## Quick Start (Vue)
64β
65```ts
66import { createA11yDevtoolsVuePlugin } from '@tanstack/devtools-a11y/vue'
67β
68const plugins = [createA11yDevtoolsVuePlugin()]
69```
70β
71## Click-to-Navigate
72β
73When you click on an issue in the panel, the plugin will:
74β
751. **Scroll** the problematic element into view (centered in the viewport)
762. **Highlight** the element with a pulsing overlay matching its severity color
773. **Show a tooltip** with the rule ID and impact level
78β
79This makes it easy to locate and inspect issues directly on the page.
80β
81## Panel Configuration
82β
83Initial configuration can be provided via the vanilla plugin API:
84β
85```ts
86import { createA11yPlugin } from '@tanstack/devtools-a11y'
87β
88const plugin = createA11yPlugin({
89 threshold: 'serious',
90 ruleSet: 'wcag21aa',
91 showOverlays: true,
92 persistSettings: true,
93 disabledRules: [],
94})
95```
96β
97Common `options` fields:
98β
99- `threshold`: minimum impact level to show
100- `ruleSet`: rule preset (`'wcag2a' | 'wcag2aa' | 'wcag21aa' | 'wcag22aa' | 'section508' | 'best-practice' | 'all'`)
101- `showOverlays`: highlight issues in the page
102- `persistSettings`: store config in localStorage
103- `disabledRules`: rule IDs to ignore
104β
105If you don't need to provide initial configuration, you can use the framework plugin helpers
106directly (the settings UI persists changes to localStorage by default).
107β
108## Severity Levels
109β
110Issues are categorized by impact level with corresponding overlay colors:
111β
112| Impact | Color | Description |
113|--------|-------|-------------|
114| Critical | Red | Must be fixed - prevents users from accessing content |
115| Serious | Orange | Should be fixed - significantly impacts user experience |
116| Moderate | Yellow | Consider fixing - affects some users |
117| Minor | Blue | Optional improvement - minor impact |
118β
119## Framework Support
120β
121The panel UI is implemented in Solid and wrapped for React, Solid, Preact, and Vue
122using `@tanstack/devtools-utils`.
123β
124## Export Formats
125β
126### JSON Export
127β
128```ts
129import { exportToJSON } from '@tanstack/devtools-a11y'
130β
131const jsonString = exportToJSON(auditResult)
132```
133β
134### CSV Export
135β
136```ts
137import { exportToCSV } from '@tanstack/devtools-a11y'
138β
139const csvString = exportToCSV(auditResult)
140```
141β
142## Supported Standards
143β
144The plugin supports the following accessibility standards:
145β
146- **WCAG 2.0** Level A, AA, AAA
147- **WCAG 2.1** Level A, AA, AAA
148- **WCAG 2.2** Level AA
149- **Section 508**
150- **Best Practices** (non-standard recommendations)
151β
152## Troubleshooting
153β
154### Issues not appearing
155β
1561. Check that the element is visible in the viewport
1572. Ensure the element is not excluded by `excludeSelectors`
1583. Verify the selected standard includes the relevant rule
159β
160### Overlays not showing
161β
1621. Confirm overlays are enabled in the panel settings
1632. Check for CSS conflicts with `z-index` or `pointer-events`
1643. Ensure the container element exists in the DOM
165β
166## Example
167β
168See the full working example at:
169`examples/react/a11y-devtools/`
170β
171Run it with:
172```bash
173cd examples/react/a11y-devtools
174pnpm dev
175```