Accessibility 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

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()]} />
  </>,
)

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

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()]

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:

1. Scroll the problematic element into view (centered in the viewport)
2. Highlight the element with a pulsing overlay matching its severity color
3. 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: [],
})

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 show
• ruleSet: rule preset ('wcag2a' | 'wcag2aa' | 'wcag21aa' | 'wcag22aa' | 'section508' | 'best-practice' | 'all')
• showOverlays: highlight issues in the page
• persistSettings: store config in localStorage
• disabledRules: 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:

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)

import { exportToJSON } from '@tanstack/devtools-a11y'

const jsonString = exportToJSON(auditResult)

CSV Export#

import { exportToCSV } from '@tanstack/devtools-a11y'

const csvString = exportToCSV(auditResult)

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#

1. Check that the element is visible in the viewport
2. Ensure the element is not excluded by excludeSelectors
3. Verify the selected standard includes the relevant rule

Overlays not showing#

1. Confirm overlays are enabled in the panel settings
2. Check for CSS conflicts with z-index or pointer-events
3. 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

cd examples/react/a11y-devtools
pnpm dev