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.

Getting Started

To install and add the module, you can run the following command:

npx nuxt module add a11y

The 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.

Features

🔍 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 generate with CI integration support.

Visual Interface within DevTools

Nuxt Accessibility provides a rich, interactive UI inside the Nuxt DevTools panel.

Dashboard Overview

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

Violation Cards

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

Highlighting

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

How It Works

Automated Accessibility Testing

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

Element Highlighting

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

Auto-Scan - Constant Scanning Mode

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

Configuration

Module Options

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,
    },
  },
})

Configuration Options

`enabled`

Type: boolean
Default: true (in development mode only)

Enable or disable the accessibility module. By default, the module only runs in development mode.

`defaultHighlight`

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
}

`logIssues`

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
}

`axe.options` & `axe.runOptions`

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'],
    },
  },
}

Build-Time Report Generation

The module generates accessibility reports during nuxt generate or prerendering. It writes the reports as markdown files, grouping violations by impact level.

`report.enabled`

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,
  },
}

`report.output`

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
  },
}

`report.failOnViolation`

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
  },
}

Example Report Output

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: ...

Development

# 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