🔥 HEADS UP! You are in the Vue 3 compatible branch, check the branch for Vue 2 support.
Imagine browsing pages (routes), receiving alerts and notifications, having a countdown timer on the page, a progress bar, a loading or a change of route in a SPA. Now imagine all this happening to people who have visual disabilities and who use screen readers.
The @vue-a11y/announcer@next (v3.*) for Vue 3 provides an easy way to really tell what’s going on in your application to people using screen readers.
npm install -S @vue-a11y/announcer@next # or yarn add @vue-a11y/announcer@next
In your main.(js|ts)
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import VueAnnouncer from '@vue-a11y/announcer'
import '@vue-a11y/announcer/dist/style.css'
createApp(App)
.use(VueAnnouncer)
.use(router)
.mount('#app')
In your App.vue
<template> <VueAnnouncer /> ... </template>
You can import the style via the @vue-a11y/announcer/dist/index.css path as in the previous one.
However, if you are using a CSS tool like TailwindCSS or Bootstrap, you don't need to import the @vue-a11y/announcer style, as you just add the sr-only class to the component.
<template> <VueAnnouncer class="sr-only" /> ... </template>
We provide the Vue composition useAnnouncer to announce to a person with a screen reader any information needed, anywhere in your app and in real time.
import { useAnnouncer } from '@vue-a11y/announcer'
const { assertive } = useAnnouncer()
assertive('My error notification')
// or
const { polite } = useAnnouncer()
polite('My info notification')
You can also use this.$announcer in your component.
export default {
// ...
methods: {
setError() {
this.$announcer.assertive('My notification error')
}
}
}
If you need to set the routeComplement option dynamically without reloading the application, for example if you're dynamically loading translations, you can use this method to update it.
export default {
setup () {
const { setRouteComplement } = useAnnouncer()
function onTranslationsUpdated (translations) {
/* 'ha cargado' e.g. in spanish */
setRouteComplement(translations.routeComplementKey)
}
// ...
}
}
export default {
// ...
methods: {
onTranslationsUpdated (translations) {
/* 'Foi carregada' e.g. in portuguese */
this.$announcer.setRouteComplement(translations.routeComplementKey)
}
}
}
For page changes (routes) to be announced automatically, you only need to pass the router object as a parameter at the time of installation.
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import VueAnnouncer from '@vue-a11y/announcer'
import '@vue-a11y/announcer/dist/index.css'
createApp(App)
.use(VueAnnouncer, { router })
.use(router)
.mount('#app') Key Data Type data default router Router false message String '' politeness String polite, assertive, off polite routeComplement String has loaded Custom announcer (object meta)
You can customize the message by defining the announcer on the "meta" object for each specific route.
{
name: 'home',
path: '/',
component: Home,
meta: {
announcer: {
message: 'Página de inicio se'
}
}
}
When the page loads, the screen reader user will hear:
Página de inicio se ha cargado.Key Data Type data default
message String document.title politeness String polite, assertive, off polite skip Boolean false routeComplement String has loaded or set at installation
@vue-a11y/announcer@next uses the global after hooks router.afterEach to announce the route changes.Necessary for dynamic content pages that require asynchronous data to compose the page title.
The skip property on the meta.announcer object is used to skip the automatic announcement made on the router.afterEach, that way you can announce when the asynchronous data is available.
For example:
In you routes.js
{
name: 'post',
path: '/posts/:id',
component: Post,
meta: {
announcer: {
skip: true
}
}
}
"Using JavaScript, it is possible to dynamically change parts of a page without requiring the entire page to reload — for instance, to update a list of search results on the fly, or to display a discreet alert or notification which does not require user interaction. While these changes are usually visually apparent to users who can see the page, they may not be obvious to users of assistive technologies. ARIA live regions fill this gap and provide a way to programmatically expose dynamic content changes in a way that can be announced by assistive technologies."
--- ARIA live regions - Accessibility | MDN
You can use the options polite, assertive and off, if no configuration is defined, the default is off.
It is used in most situations that present new information to users.
The notification will take place at the next available point, without interruptions.
NOTE: polite is default
It is used in situations where the notification is important enough to communicate it immediately, for example, error messages or alerts.
const { assertive } = useAnnouncer()
assertive('My error notification')
Is the default and prevent assistive technology from keeping up with changes.
Vue Announcer was tested and works as expected in the latest versions of:
Follow us on Twitter @vue_a11y
Thank you
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4