Vue A11y Community & Toolkit

1.0.0 verified Thu Apr 23 auth: no javascript renamed

Vue A11y represents a community-driven initiative focused on improving web accessibility within the Vue.js ecosystem. It is not a single, monolithic npm package but rather an umbrella organization (`@vue-a11y`) coordinating several specialized packages, tools, and guidelines designed to help developers build accessible Vue applications. Key projects under this umbrella include `@vue-a11y/announcer` for screen reader announcements, `@vue-a11y/skip-to` for keyboard navigation, `@vue-a11y/focus-loop` for managing focus traps, and `eslint-plugin-vuejs-accessibility` for linting a11y issues. While specific packages are actively maintained, the generic 'vue-a11y' name typically refers to the collective effort or an earlier, foundational concept that has since evolved into a modular approach. This modularity allows developers to pick and choose specific accessibility features as needed, supporting both Vue 2 and Vue 3 depending on the individual package. Release cadence varies per sub-package, but the community actively updates tools and resources to align with WCAG standards and Vue.js advancements.

Common errors

error Cannot find module 'vue-a11y' or its corresponding type declarations. ↓

cause The package 'vue-a11y' as a single entity is not the primary way to consume these tools anymore. Functionality is provided by scoped packages.

fix

Install the specific @vue-a11y/* package you intend to use, e.g., npm install @vue-a11y/announcer or yarn add @vue-a11y/announcer.

error ESLint: Rule 'vuejs-accessibility/heading-has-content' is not found. ↓

cause The ESLint plugin is either not installed, incorrectly configured, or an older version is missing newer rules. Or, you might be using an outdated rule name.

fix

Ensure eslint-plugin-vuejs-accessibility is installed (npm install --save-dev eslint-plugin-vuejs-accessibility) and configured in your .eslintrc.js with extends: ['plugin:vuejs-accessibility/recommended']. Check the plugin's documentation for the correct rule names.

error Screen reader does not announce dynamic content updates or route changes in my Vue SPA. ↓

cause Vue applications, especially SPAs, don't automatically manage `aria-live` regions or focus for screen readers on route changes or dynamic content updates.

fix

Implement @vue-a11y/announcer for dynamic announcements and ensure proper focus management. For route changes, use a skip link and programmatically set focus to the main content area or the page title.

Warnings

breaking The generic `vue-a11y` package name (if it ever existed as a central installable library) is effectively deprecated and has been superseded by a collection of scoped `@vue-a11y/*` packages. Direct migration from a hypothetical `vue-a11y` v1.x to current versions requires installing specific scoped modules. ↓

fix Identify required accessibility features and install the corresponding `@vue-a11y/*` package (e.g., `@vue-a11y/announcer`, `@vue-a11y/skip-to`). Review the documentation for each specific package.

gotcha Vue 2 and Vue 3 have distinct APIs and patterns, particularly for composition API vs options API and reactivity. Ensure that the `@vue-a11y/*` packages you install are compatible with your specific Vue version. For instance, `@vue-a11y/announcer` has separate branches/versions for Vue 2 and Vue 3. ↓

fix Always check the specific `@vue-a11y/*` package's documentation or `package.json` for supported Vue versions. Often, Vue 3 versions are in `next` branches or separate releases.

breaking `eslint-plugin-vuejs-accessibility` (a key `vue-a11y` tool) has seen updates to its rules and configuration. Older configurations or rule names might be deprecated or behave differently in newer versions, especially when migrating ESLint setups. ↓

fix Refer to the `eslint-plugin-vuejs-accessibility` documentation for the latest recommended configuration and rule details. Update your `.eslintrc.js` to extend `plugin:vuejs-accessibility/recommended` and address any linter warnings.

gotcha Many accessibility features, such as focus management and ARIA attributes, require careful manual implementation even with dedicated libraries. Relying solely on components might not cover all edge cases or dynamic content changes, especially in Single Page Applications (SPAs). ↓

fix Supplement library usage with manual accessibility testing, including keyboard navigation and screen reader checks. Integrate tools like `@vue-a11y/vue-axe-next` for automated auditing during development and consult WCAG guidelines and WAI-ARIA authoring practices.

Install

npm install vue-a11y

yarn add vue-a11y

pnpm add vue-a11y

Imports

Announcer
wrong
```
import Announcer from 'vue-a11y'; // Incorrect package name for components
```
correct
```
import { Announcer } from '@vue-a11y/announcer'
```
The generic 'vue-a11y' package is not directly imported for components; use specific scoped packages like @vue-a11y/announcer.

SkipTo

wrong

const SkipTo = require('vue-a11y'); // CommonJS is usually not supported for modern Vue components; use ESM.

correct

import { SkipTo } from '@vue-a11y/skip-to'

Most @vue-a11y packages are primarily designed for ESM environments in modern Vue projects.

eslint-plugin-vuejs-accessibility

wrong

import 'eslint-plugin-vuejs-accessibility'; // Not imported as runtime code; configured in ESLint.

correct

module.exports = { plugins: ['vuejs-accessibility'] }; // In .eslintrc.js

This is an ESLint plugin, configured in your ESLint config, not imported into application code.

Quickstart

This quickstart demonstrates the use of `@vue-a11y/announcer` to provide dynamic screen reader announcements for content changes and navigation, crucial for single-page applications.

<!-- src/App.vue -->
<template>
  <div id="app">
    <Announcer assertive />
    <nav>
      <button @click="announceStatus('Navigating to Home...')">Home</button>
      <button @click="announceStatus('Navigating to About...')">About</button>
    </nav>
    <main>
      <h1>Welcome to the Accessible App</h1>
      <p>{{ currentMessage }}</p>
      <button @click="updateMessage">Update Status</button>
      <input type="text" aria-label="Enter your name" placeholder="Your name">
    </main>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { Announcer } from '@vue-a11y/announcer';

const currentMessage = ref('Initial content loaded.');
const announcer = new Announcer(); // For programmatic announcements

function updateMessage() {
  const newMessage = 'Content updated successfully!';
  currentMessage.value = newMessage;
  announcer.polite(newMessage); // Announce politely to screen readers
}

function announceStatus(status) {
  announcer.assertive(status); // Announce assertively
}
</script>

<style>
body { font-family: sans-serif; margin: 2rem; }
nav button, main button { margin-right: 10px; padding: 8px 15px; }
input { padding: 8px; margin-top: 15px; display: block; }
</style>