Vue Accessibility: The Complete WCAG 2.2 Guide

The WCAG 2.2 Criteria Vue Apps Break Most

For the full list, see the WCAG 2.2 Level AA requirements and the interactive WCAG 2.2 checklist.

2. Bind ARIA Reactively with :aria-*

Vue's v-bind (the : shorthand) sets ARIA attributes directly, and it stringifies booleans for you — :aria-expanded="isOpen" renders aria-expanded="true" or "false". The rule that trips teams up is what Vue does with empty values: when a bound expression is null or undefined, Vue removes the attribute entirely. That is exactly what you want for conditional states.

<!-- Boolean state: renders aria-expanded="true" / "false" -->
<button :aria-expanded="isOpen" :aria-controls="panelId">Menu</button>

<!-- Conditional attribute: present only when there is an error,
     removed entirely when the expression is null -->
<input :aria-invalid="hasError || null" :aria-describedby="hasError ? 'err' : null" />

<!-- Token attributes: bind the token, not a bare boolean -->
<a :aria-current="isActive ? 'page' : null" :href="href">Home</a>

<!-- Many ARIA attributes at once with the object form of v-bind -->
<div v-bind="{ role, 'aria-expanded': open, 'aria-controls': panelId }" />

Bind null (not false) when you want an attribute to disappear — binding false renders the literal string aria-invalid="false", which is correct for a true/false ARIA state but wrong for attributes like aria-describedby that should simply be absent. For token attributes such as aria-current, bind the token ('page') rather than a boolean so screen readers announce the right thing. Every role and state is documented in our ARIA roles & attributes reference.

4. Manage Focus on Vue Router Navigation

When Vue Router changes routes, the browser does not reset focus the way a full page load would. Keyboard and screen reader users are left on whatever link they activated, now pointing at content that no longer exists. Move focus to the top of the new view in router.afterEach() — after a nextTick() so the new component has actually rendered.

// router/index.ts
import { createRouter, createWebHistory } from "vue-router"
import { nextTick } from "vue"

const router = createRouter({
  history: createWebHistory(),
  routes: [/* ... */],
})

router.afterEach(async () => {
  await nextTick()
  const main = document.querySelector<HTMLElement>("main")
  main?.focus()
})

export default router

<!-- App.vue -->
<template>
  <a class="skip-link" href="#main">Skip to main content</a>
  <nav aria-label="Primary"><!-- ... --></nav>

  <main id="main" tabindex="-1">
    <RouterView />
  </main>
</template>

tabindex="-1" lets <main> receive programmatic focus without adding it to the Tab order. Prefer focusing a container or the new <h1> over announcing the whole page. This satisfies 2.4.3 Focus Order and depends on a working skip link. For the full picture of programmatic focus, traps, and restoration, see the focus management guide.

6. Announce Dynamic Content (and the v-if Trap)

Reactivity updates the DOM silently. When search results load, a toast appears, or a form saves, a sighted user sees it instantly — a screen reader user hears nothing unless the change happens inside an aria-live region. The Vue-specific catch: a screen reader only announces a live region that already existed in the DOM before its content changed. Mount that region with v-if at the moment the message appears and nothing is announced.

<!-- Broken: the region is created at the same moment as its text,
     so the browser treats it as initial content, not an update -->
<p v-if="message" aria-live="polite">{{ message }}</p>

<!-- Correct: the region is always in the DOM; only its text changes -->
<p aria-live="polite" class="sr-only">{{ message }}</p>

// A reusable announcer composable — one persistent region for the app
// composables/useAnnouncer.ts
import { ref } from "vue"

const message = ref("")
export function useAnnouncer() {
  function announce(text: string) {
    message.value = ""            // reset so identical messages re-announce
    requestAnimationFrame(() => { message.value = text })
  }
  return { message, announce }
}

Render one always-mounted, visually hidden region near the root (<p aria-live="polite" class="sr-only">{{ message }}</p>) and drive it from the composable. Use v-show rather than v-if if you must toggle visibility, since it keeps the element in the DOM. Reserve aria-live="assertive" for urgent, interrupting messages such as a session-timeout warning. This satisfies 4.1.3 Status Messages.

7. Accessible Forms with v-model

v-model handles the data binding, but says nothing about accessibility. Associate every input with a <label>, then link the error message with :aria-describedby and mark the field with :aria-invalid — binding null so the attributes disappear when the field is valid.

<script setup lang="ts">
import { ref, computed } from "vue"

const email = ref("")
const touched = ref(false)
const emailInvalid = computed(
  () => touched.value && !/^[^@]+@[^@]+\.[^@]+$/.test(email.value)
)
</script>

<template>
  <form @submit.prevent="submit">
    <label for="email">Email</label>
    <input
      id="email"
      type="email"
      v-model="email"
      @blur="touched = true"
      :aria-invalid="emailInvalid || null"
      :aria-describedby="emailInvalid ? 'email-error' : null"
    />
    <p v-if="emailInvalid" id="email-error" class="error">
      Enter a valid email address.
    </p>

    <button type="submit">Create account</button>
  </form>
</template>

Never rely on a placeholder as the label — it disappears on input and usually fails contrast. Only surface aria-invalid and aria-describedby once the user has touched the field (here, on @blur), so assistive tech is not told about an error before it is shown. The error message text sits inside a v-if — that is fine, because aria-describedby resolves the id when it exists; it is only live regions that must stay mounted. For labels, grouping with <fieldset>, validation, and error summaries, see the accessible forms guide and 3.3.1 Error Identification.

8. Testing & Tooling

Automated checks catch a meaningful share of issues and stop regressions — but they find roughly a third to a half of WCAG problems, so they supplement rather than replace manual testing. Layer three tools into your Vue workflow:

// 1. Lint templates — eslint-plugin-vuejs-accessibility
//    In eslint.config.js, extend "plugin:vuejs-accessibility/recommended".
//    Key rules:
//    "vuejs-accessibility/click-events-have-key-events"
//    "vuejs-accessibility/form-control-has-label"
//    "vuejs-accessibility/anchor-has-content"
//    "vuejs-accessibility/aria-props"
//    "vuejs-accessibility/alt-text"

// 2. Component tests: @testing-library/vue + vitest-axe
import { render } from "@testing-library/vue"
import { axe } from "vitest-axe"
import TextField from "./TextField.vue"

it("TextField has no axe violations", async () => {
  const { container } = render(TextField, {
    props: { label: "Email", id: "email" },
  })
  expect(await axe(container)).toHaveNoViolations()
})

// 3. End-to-end: axe-core in Playwright against real routes
import AxeBuilder from "@axe-core/playwright"

test("home page is accessible", async ({ page }) => {
  await page.goto("/")
  const results = await new AxeBuilder({ page }).analyze()
  expect(results.violations).toEqual([])
})

Vue Testing Library nudges you toward accessible queries — getByRole and getByLabelText only pass when the accessibility tree is correct, so writing tests this way surfaces missing names and broken $attrs forwarding early. Finish every feature with a manual keyboard pass and a screen reader pass. Read our comparison of automated vs manual testing to see where each fits.

Vue Accessibility Checklist

1. Semantic templates. Every clickable thing is a <button> or <a>/<RouterLink>; headings are ordered; one <h1> per view.
2. Reactive ARIA. Dynamic ARIA uses :aria-* and binds null to remove attributes when off.
3. Attribute fallthrough. Wrapper components set inheritAttrs: false and v-bind="$attrs" on the real control.
4. Focus on navigation. router.afterEach moves focus to <main> or the new heading after nextTick().
5. Overlays. Dialogs use <Teleport>, trap focus, close on Escape, and restore focus.
6. Live regions. Async results and errors announce from an always-mounted aria-live region (not v-if).
7. Forms. Labels associated; errors linked with :aria-describedby and :aria-invalid.
8. Automated + manual. eslint-plugin-vuejs-accessibility + vitest-axe in CI, plus a keyboard and screen reader pass.

Scan the deployed build with our URL accessibility auditor and work through the full WCAG 2.2 checklist.