A Nuxt module that provides real-time accessibility feedback and automated testing right in your browser during development.
Nuxt Accessibility integrates directly into the Nuxt DevTools, giving you actionable insights to fix WCAG violations, improve accessibility compliance, and ensure your application is usable by everyone without ever leaving your development environment.
To install and add the module, you can run the following command:
npx nuxt module add a11yThe module is now automatically installed and added to your nuxt.config.ts. Now you can open your Nuxt app, go to the DevTools, and click the Nuxt a11y icon to get started.
- 🔍 Rich DevTools UI: A tab in Nuxt DevTools to visualize accessibility violations, inspect elements, and get recommendations.
- ⚡️ Powered by axe-core: Industry-leading accessibility testing engine used by Google, Microsoft, and thousands of developers worldwide.
- 🎨 Element Highlighting: Click any violation to highlight and pin affected elements on your page with numbered badges.
- 🎯 Impact-Based Organization: Violations categorized by severity (critical, serious, moderate, minor) to help you prioritize fixes.
- 🔄 Results based on Routes: Automatically tracks violations across all routes as you navigate your application.
- ⚙️ Auto-Scan - Constant Scanning Mode: Automatically scans for accessibility issues every time you interact with the app.
- 🎛️ Configurable Options: Auto-highlight all violations, customize axe-core settings, and control console logging.
- 📋 Build-Time Reports: Generate accessibility reports during
nuxt generatewith CI integration support.
Nuxt Accessibility provides a rich, interactive UI inside the Nuxt DevTools panel.
A central hub showing:
- Total violations and affected elements across your application
- Violations grouped by impact level (critical, serious, moderate, minor)
- Violation counts per page
- Control panel for manual scans, auto-scanning, and clearing results
Each violation displays:
- Impact badge with color-coded severity
- Rule ID and description from WCAG/axe-core
- Learn more link to detailed documentation
- Affected elements count with expandable details
- Interactive element badges to pin/unpin specific elements
- CSS selectors for each affected element
- Scroll-to-element button to jump to the affected element on the page
- Click violation cards to highlight all affected elements on your page
- Numbered badges label each highlighted element so it maps to its violation
- Click individual elements to toggle highlighting for specific nodes
- Scroll-to-element button jumps to the element's location on the page
- Route-aware highlighting shows which violations belong to the current page
Nuxt Accessibility uses axe-core to perform comprehensive accessibility audits. The module automatically:
- Runs accessibility scans when you navigate to a new page
- Detects violations against WCAG 2.0, WCAG 2.1, WCAG 2.2, and best practices
- Groups violations by impact level and tracks them across routes
- Provides detailed information about each violation including CSS selectors, failure summaries, and remediation guidance
The module hooks into your application to provide interactive debugging:
- Click-to-pin: Click any violation to pin and highlight affected elements with numbered badges
- Hover positioning: Badges dynamically follow elements as you scroll
- Route tracking: Violations are associated with specific routes for better organization
- Smart root element handling: Prevents highlighting of
<html>and<body>tags with helpful notifications
Enable optional real-time scanning that listens to user interactions:
- Monitors mouse, keyboard, and touch events
- Debounced scanning to prevent performance issues
- Automatically detects new violations as DOM changes occur
- Can be toggled on/off from the DevTools control panel
export default defineNuxtConfig({
modules: ['@nuxt/a11y'],
a11y: {
// Enable/disable the module (default: true in dev mode)
enabled: true,
// Auto-highlight all violations when detected
defaultHighlight: false,
// Log violations to browser console
logIssues: true,
// Configure axe-core
axe: {
// axe-core configuration options
options: {},
// axe-core run options
runOptions: {},
},
// Build-time report generation
report: {
// Enable report generation (default: true in production)
enabled: true,
// Output path for the report (relative to .nuxt/)
output: 'a11y-report.md',
// Exit with code 1 when violations are found
failOnViolation: true,
},
},
})- Type:
boolean - Default:
true(in development mode only)
Enable or disable the accessibility module. By default, the module only runs in development mode.
- Type:
boolean - Default:
false
Automatically highlight all accessibility violations when they are detected. When enabled, the module pins and highlights all violations on the current page with numbered badges.
a11y: {
defaultHighlight: true, // Auto-highlight all violations
}- Type:
boolean - Default:
true
Controls whether the module logs accessibility violations to the browser console. When enabled, the module logs violations with appropriate styling and severity levels.
a11y: {
logIssues: false, // Disable console logging
}- Type:
object - Default:
{}
Configure the underlying axe-core runner. See the axe-core documentation for available options.
a11y: {
axe: {
options: {
// Customize which rules to run
rules: [
{ id: 'color-contrast', enabled: true },
],
},
runOptions: {
// Customize how axe-core runs
runOnly: ['wcag2a', 'wcag2aa'],
},
},
}The module generates accessibility reports during nuxt generate or prerendering. It writes the reports as markdown files, grouping violations by impact level.
- Type:
boolean - Default:
true(in production/generate mode)
Enable or disable build-time report generation. The report runs automatically during nuxt generate and scans all prerendered routes.
a11y: {
report: {
enabled: true,
},
}- Type:
string - Default:
'a11y-report.md'
The output path for the generated report, resolved relative to the .nuxt/ directory.
a11y: {
report: {
output: 'a11y-report.md', // Results in .nuxt/a11y-report.md
},
}- Type:
boolean - Default:
true
Exit with a non-zero code when accessibility violations are found. This enables CI pipelines to fail builds that contain accessibility issues.
a11y: {
report: {
failOnViolation: true, // CI will fail if violations exist
},
}The generated report groups violations by impact level:
# Accessibility Report
Generated: 2026-01-08
Routes scanned: 5
Total violations: 23
## Critical (6)
### image-alt
**Images must have alternative text** | Routes: /, /about
Elements:
- `.hero-image` - Fix any of the following: ...# Install dependencies
pnpm install
# Generate type stubs
pnpm dev:prepare
# Develop with the playground
pnpm dev
# Build the module and client
pnpm build
# Run ESLint
pnpm lint
# Run Vitest
pnpm test
pnpm test:watch
# Release new version
pnpm release