Vue 3

@a11y-hud/vue is a thin Vue 3 adapter that mounts the a11y-hud Custom Element in onMounted and re-runs axe when the scope prop changes (post-flush watch). General DOM updates are picked up by the core's MutationObserver.

Requirements

• Vue 3.4 or later
• a11y-hud (installed automatically as a dependency)

Install

npm

npm install --save-dev @a11y-hud/vue

pnpm

pnpm add -D @a11y-hud/vue

yarn

yarn add -D @a11y-hud/vue

Quick start — component

App.vue

<script setup lang="ts">
import { A11yHud } from "@a11y-hud/vue";

const isDev = import.meta.env.DEV;
</script>

<template>
  <A11yHud v-if="isDev" theme="auto" />
  <!-- rest of app -->
</template>

Server-side rendering

Importing @a11y-hud/vue is safe on the server (Nuxt, Vite SSR): the Custom Element is only registered when customElements exists. The HUD mounts in onMounted, which runs only in the browser, so nothing is rendered server-side. In Nuxt you can drop <A11yHud> straight into app.vue; wrapping it in <ClientOnly> is optional.

Quick start — composable

import { useA11yHud } from "@a11y-hud/vue";

const hud = useA11yHud({ theme: "auto" });

Props / options

Prop	Type	Default	Description
theme	Theme	"auto"	Visual theme
scope	Element | null	—	Scan scope element. Pass a template ref directly (:scope="myRef") — Vue templates auto-unwrap refs.
autoScan	boolean	true	Re-scan on DOM mutations
debounce	number	500	Auto-scan debounce in ms
runOnly	string[]	—	axe rule tags to run

Scoping to a subtree

Pass a Vue template ref as scope:

<script setup lang="ts">
import { ref } from "vue";
import { A11yHud } from "@a11y-hud/vue";

const appRoot = ref<HTMLDivElement | null>(null);
</script>

<template>
  <A11yHud theme="auto" :scope="appRoot" />
  <div ref="appRoot">
    <!-- only this subtree is scanned -->
  </div>
</template>

Route-change rescans

Vue Router navigations mutate the DOM, which the core's MutationObserver picks up automatically (debounced). Changing the scope prop also triggers an immediate rescan. For explicit control, see the Route-change rescans cookbook.

Instance API

const hud = useA11yHud({ theme: "auto" });

hud.runScan()              // Promise<AxeResults | null> — null if not mounted yet
hud.setTheme("github-dark")
hud.setRunOnly(["wcag2a"])
hud.exportResults()
hud.ignores.add("color-contrast")
hud.ignores.list()
hud.ignores.exportJson()
hud.ignores.importJson(json)
hud.ignores.clear()

See UseA11yHudReturn for full type details.