Skip to content
Tutorials Center
My learning

Topics

Lesson 57 of 87 ยท TypeScript and Quality

Accessibility in Vue

Build accessible Vue apps with semantic HTML, focus management, ARIA bindings, route announcements, an accessible modal and an accessible form with errors.

Accessibility (often shortened to a11y) means that people can use your app whatever way they interact with it: keyboard only, screen reader, voice control, magnification, or a slow device. It is also what makes forms usable on a phone and makes sites pass legal requirements in many countries.

Vue does not make an app accessible or inaccessible by itself. A single-page app, however, removes things the browser used to do for free on every page load: it no longer resets focus, announces a new page title or restores the scroll position. So Vue developers must do a few things deliberately. This lesson covers the ones that matter most, each with a runnable example you can operate with your keyboard.

Start with semantic HTML

The cheapest accessibility win is using the right element. A native <button> is focusable, activates with Enter and Space, and is announced as a button. A <div @click="save"> is none of those, so keyboard and screen reader users cannot use it.

HTML
<!-- Avoid: mouse-only -->
<div class="btn" @click="save">Save</div>

<!-- Prefer -->
<button type="button" @click="save">Save</button>

The same applies across the page:

  • Use landmarks (<header>, <nav>, <main>, <footer>) so assistive technology can jump between regions, and put one <h1> per view with headings in order.
  • Use <a href> for navigation and <button> for actions.
  • Use real lists, tables and form controls instead of styled divs.
  • Connect every form control to a <label>, and give images meaningful alt text (or alt="" for decoration).

ARIA attributes add meaning when no native element exists. The first rule of ARIA is to prefer a native element; the second is that bad ARIA is worse than none.

ARIA attributes with v-bind

ARIA state attributes are ordinary attributes, so you bind them like any other (Binding Attributes):

HTML
<button
  type="button"
  :aria-expanded="open"
  aria-controls="menu"
  @click="open = !open"
>
  Menu
</button>
<ul id="menu" v-show="open">...</ul>

Vue renders aria-expanded="true" and aria-expanded="false" for a boolean (it keeps false for non-boolean attributes), and removes the attribute entirely for null or undefined. Use that to your advantage: :aria-invalid="hasError ? 'true' : null" adds the attribute only when it is needed. Other common ones are aria-pressed for toggle buttons, aria-current="page" on the active nav link, aria-describedby for hints and errors, and aria-live regions for announcements.

For unique ids (a label's for and an input's id, or aria-describedby), do not hard-code a string in a reusable component, because two instances would share it. Vue 3.5 provides useId(), which returns an id that is unique within the app (and stable between server and client rendering).

Focus management

Focus is where keyboard input goes, and it is the thing an SPA most often loses. Three situations need your attention:

  1. After an action that changes the page, such as opening a dialog or navigating to a new view, move focus to the new content.
  2. When a transient layer closes, return focus to the control that opened it.
  3. When validation fails, move focus to the first invalid field.

The tools are a template ref, nextTick (to wait for Vue to update the DOM, see DOM Update Timing and nextTick), and the element's focus() method. To focus something that is not normally focusable, such as a heading, give it tabindex="-1": it can then receive focus from code but is not added to the Tab order.

An accessible modal

Teleport and KeepAlive built the visual part of a modal. To make it accessible, the dialog needs:

  • role="dialog", aria-modal="true" and a name (aria-labelledby pointing at its heading),
  • focus moved inside when it opens,
  • Tab and Shift+Tab kept inside it (a focus trap),
  • Escape to close, and
  • focus returned to the opener when it closes.
flowchart LR
  A["Opener button<br/>has focus"] --> B["Dialog opens<br/>focus moves to first control"]
  B --> C["Tab and Shift+Tab loop<br/>inside the dialog"]
  C --> D["Escape or Close"]
  D --> E["Dialog removed<br/>focus returns to the opener"]

The user's place in the page is preserved: they leave from the opener and come back to it.

The example stores the opener before opening and restores it afterwards. A status line prints which element currently has focus, so you can follow it with Tab.

A modal with focus management

Open the dialog with Enter or Space on the button. Focus lands in the text input. Press Tab repeatedly: it cycles through the input and both buttons and never leaves the dialog. Press Escape and focus returns to "Delete account".

This is a teaching version. Production dialogs also hide the rest of the page from screen readers (with the native inert attribute or aria-hidden), lock background scrolling and handle nested dialogs. For anything beyond a simple modal, consider a headless library that already does this (see Styling Strategies), or the native <dialog> element with showModal(), which provides a focus trap and Escape handling for you.

An accessible form

Forms fail accessibility in predictable ways: missing labels, errors shown only in red, and errors that screen readers never hear. The pattern that works:

  • every input has a visible <label> connected with for and id;
  • an invalid input gets aria-invalid="true" and aria-describedby pointing at its error message;
  • when submission fails, show a summary with role="alert" (it is announced when it appears) and move focus to the first invalid field;
  • never rely on color alone: the message text is what carries the meaning.

The FormField component below uses useId() so each instance has its own ids. Submit it empty, then fill it in. (Forms in this site's runner never post anywhere; the valid result is printed instead, as in Building Forms.)

Errors that assistive technology can find

After a failed submit, the summary appears, both fields show messages tied to their inputs, and focus jumps to the first invalid input, so a keyboard or screen reader user lands exactly where the problem is.

Announcing route changes

On a normal website, each navigation loads a new document: the title changes, focus resets to the top, and a screen reader starts reading the new page. In an SPA, changing the view silently swaps the DOM, and a screen reader user may not know anything happened. Two techniques fix this, and you should choose one so the change is not announced twice:

  • Move focus to the new view's heading (an <h1 tabindex="-1">). The screen reader announces it.
  • Use a live region: a visually hidden element with aria-live="polite" whose text you update with "Navigated to Docs".

In both cases also update document.title, since it is what history lists and tabs show. With Vue Router you do this in a global router.afterEach hook (Vue Router Advanced Features). The sandbox here has no router, so the example uses a plain current ref as a stand-in. The switcher lets you compare the two techniques.

flowchart TD
  A["User activates a link"] --> B["View changes in the DOM"]
  B --> C["Update document.title"]
  C --> D{"Announcement strategy"}
  D -->|"move focus"| E["Focus the new h1"]
  D -->|"live region"| F["Update aria-live text"]

The browser no longer announces navigation for you, so the app does it.

Announce navigation in a single-page view

Pick a link and watch the report: the title always updates. In "focus" mode the heading receives focus (you will see the dashed outline), and in "live region" mode the hidden region receives the announcement text.

Testing accessibility

Automated tools find roughly the mechanical half of the problems, so combine them with manual checks:

  1. Keyboard only. Unplug the mouse: can you reach and use everything, in a logical order, with a visible focus indicator?
  2. A screen reader (NVDA or Narrator on Windows, VoiceOver on macOS and iOS, TalkBack on Android) on your key flows.
  3. Automated checks: the axe DevTools browser extension or Lighthouse for pages, and eslint-plugin-vuejs-accessibility for templates in your editor and CI (see Code Quality and Style).
  4. Zoom to 200 percent and check contrast. Text and controls need enough contrast with their background (4.5:1 for normal text in WCAG).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why should a clickable control usually be a <button> instead of a <div @click>?

    Native elements give keyboard support and semantics for free. A div has neither, and ARIA roles alone do not add keyboard handling.
  2. 2. What does Vue do with :aria-invalid="hasError ? 'true' : null" when hasError is false?

    Binding null or undefined removes an attribute. This is the easy way to add an ARIA attribute only when it applies.
  3. 3. A dialog closes. Where should focus go?

    Returning focus to the opener keeps keyboard and screen reader users in the place they came from.
  4. 4. Why should an SPA announce route changes?

    A client-side navigation does not reload the document, so the usual announcement and focus reset do not happen. Move focus to the new heading or update an aria-live region (not both), and update the document title.
  5. 5. What is the purpose of tabindex="-1" on a heading?

    A negative tabindex makes an element programmatically focusable but keeps it out of the normal Tab sequence.

Summary

  • Use native elements first: button for actions, a href for navigation, label for every control, landmarks and ordered headings.
  • Bind ARIA state with v-bind; null removes an attribute, so you can add aria-invalid only when needed.
  • Use useId() (Vue 3.5) for ids in reusable components such as form fields.
  • Manage focus yourself in an SPA: into dialogs, back to the opener, and to the first invalid field. Use a ref, nextTick and tabindex="-1" for non-interactive targets.
  • A modal needs role="dialog", aria-modal, a name, a focus trap, Escape to close and focus restoration.
  • Forms need labels, aria-invalid, aria-describedby for messages and a role="alert" summary; do not rely on color alone.
  • Announce route changes by moving focus to the new heading or updating a live region, and update document.title.
  • Combine keyboard testing, a screen reader and automated tools such as axe and eslint-plugin-vuejs-accessibility.

Next: Testing Vue Apps