Skip to content
Source
Sign inSign up
TanStack/devtools
Open History to see the last commit

a11y.md

175 lines4.7 KB

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 </>,
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')!,
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```