eslint-plugin-vuejs-accessibility

2.5.0 verified Sat Apr 25 auth: no javascript

An ESLint plugin for checking accessibility (a11y) rules in Vue.js single-file components (.vue files). Current stable version is 2.5.0 (released 2025-03-28). It provides a set of rules to enforce WCAG and ARIA best practices, inspired by eslint-plugin-jsx-a11y but tailored for Vue templates. Released under MIT license, actively maintained by the vue-a11y community. Supports ESLint v5–v10, ship TypeScript declarations, and works with both legacy (extends) and flat config formats. Key differentiator vs. other Vue a11y tools: it is the most comprehensive and community-maintained plugin.

Common errors

error ESLint couldn't find the plugin "eslint-plugin-vuejs-accessibility". ↓

cause Missing or incorrect installation of the plugin package.

fix

Run npm install --save-dev eslint-plugin-vuejs-accessibility (or yarn equivalent). Ensure the package is in your devDependencies.

error Definition for rule 'vuejs-accessibility/alt-text' was not found. ↓

cause The rule prefix is missing or plugin not loaded correctly. Common mistake: using 'alt-text' instead of 'vuejs-accessibility/alt-text'.

fix

Prefix rule names with 'vuejs-accessibility/'. Example: 'vuejs-accessibility/alt-text': 'error'.

error Invalid plugin object, expected a plugin with a 'rules' property. ↓

cause Using the wrong import style, e.g., `import { rules } from 'eslint-plugin-vuejs-accessibility'` instead of default import.

fix

Import the plugin as default: import plugin from 'eslint-plugin-vuejs-accessibility';.

error Prop `title` is missing from template, but rule `vuejs-accessibility/alt-text` is enabled. ↓

cause The rule flags missing alt text on images; sometimes users misunderstand it expects a `title` prop instead of `alt`.

fix

Add an alt attribute to your <img> elements: <img src="..." alt="description">.

error Cannot find module 'globals' ↓

cause Missing peer dependency 'globals' required since v2.4.2.

fix

Install globals as a dev dependency: npm install --save-dev globals.

Warnings

breaking Flat config support was added in v2.3.0. Prior to v2.3.0, only legacy .eslintrc format worked with ESLint v8. ESLint v9 users must use v2.3.0+ and flat config. ↓

fix Upgrade to v2.3.0 or later. If using ESLint v9, update config to flat format as shown in quickstart.

deprecated The rule 'label-has-for' is deprecated in favor of 'form-control-has-label'. It will be removed in a future major version. ↓

fix Replace 'vuejs-accessibility/label-has-for' with 'vuejs-accessibility/form-control-has-label' in your ESLint rules.

gotcha Peer dependency 'globals' is required and must be >=13.12.1. Missing 'globals' can cause errors in flat config setups. ↓

fix Run `npm install --save-dev globals` (or appropriate version). Ensure 'globals' is listed in devDependencies.

gotcha When using flat config, the config key is 'flat/recommended' (not 'recommended'). Using 'recommended' without 'flat/' will fail. ↓

fix Use plugin.configs['flat/recommended'] in flat config; for legacy config, use extends: ['plugin:vuejs-accessibility/recommended'].

gotcha Rules must be prefixed with 'vuejs-accessibility/' in rule settings. Omitting the prefix causes ESLint to throw 'Definition for rule was not found'. ↓

fix Correct rule name format: 'vuejs-accessibility/rule-name'. Example: 'vuejs-accessibility/alt-text'.

Install

npm install eslint-plugin-vuejs-accessibility

yarn add eslint-plugin-vuejs-accessibility

pnpm add eslint-plugin-vuejs-accessibility

Imports

plugin (default export)

wrong

import { rules } from 'eslint-plugin-vuejs-accessibility';

correct

const plugin = require('eslint-plugin-vuejs-accessibility');
// or
import plugin from 'eslint-plugin-vuejs-accessibility';

The default export is the plugin object containing rules and configs. Named exports are not available.

Flat config usage (ESM)

wrong

module.exports = {
  plugins: ['vuejs-accessibility'],
  extends: ['plugin:vuejs-accessibility/recommended']
};

correct

import plugin from 'eslint-plugin-vuejs-accessibility';
export default [
  plugin.configs['flat/recommended'],
  {
    rules: {
      'vuejs-accessibility/alt-text': 'error'
    }
  }
];

Flat config is supported since v2.3.0. Legacy .eslintrc format still works. The config key for flat is 'flat/recommended' or 'flat/all'.

Legacy ESLint config (CJS)

wrong

extends: ['eslint-plugin-vuejs-accessibility/recommended']

correct

module.exports = {
  extends: ['plugin:vuejs-accessibility/recommended'],
  rules: {
    'vuejs-accessibility/alt-text': 'error'
  }
};

Use the plugin prefix 'plugin:vuejs-accessibility/' in extends, not the full npm package name.

Custom rule configuration
wrong
```
"vuejs-accessibility/click-events-have-key-events": "off"
```
correct
```
// .eslintrc
{
  'vuejs-accessibility/click-events-have-key-events': 'warn'
}
```
Rules are prefixed with 'vuejs-accessibility/'. Each rule can have severity and options. Refer to docs for individual rule options.

Quickstart

Shows both flat config (ESLint v9+) and legacy .eslintrc setup for eslint-plugin-vuejs-accessibility v2.5.0.

// Install: npm install --save-dev eslint eslint-plugin-vuejs-accessibility

// Use with Flat config (ESLint v9+, recommended):
// eslint.config.js
import plugin from 'eslint-plugin-vuejs-accessibility';
import globals from 'globals';

export default [
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node
      }
    }
  },
  plugin.configs['flat/recommended'],
  {
    rules: {
      'vuejs-accessibility/alt-text': ['error', { elements: ['img', 'area', 'input[type="image"]'] }],
      'vuejs-accessibility/click-events-have-key-events': 'warn'
    }
  }
];

// For .eslintrc (legacy, ESLint v8):
// .eslintrc.js
module.exports = {
  extends: ['plugin:vuejs-accessibility/recommended'],
  rules: {
    'vuejs-accessibility/alt-text': 'error'
  }
};