Accessibility
What awesome-tour does for keyboard, screen reader and motion-sensitive users — and what's left to you.
Accessibility is built into the primitives, so it’s on even when you restyle everything.
Beat A
16 steps · drumsMixer
4 channelsWhat a screen reader gets
Start the tour with the keyboard (Tab to “Start tour”, Enter), then use ← → and Tab.
import { createTour, Tour } from '@awesome-tour/react';import { LoopworkApp, parts } from '@loopwork';import { useEffect, useState } from 'react';import { TourPopover } from '@/components/awesome-tour/tour';import { DemoFrame, StartButton } from './ui';
const $ = parts('heard');
const tour = createTour({ id: 'docs-a11y', steps: [ { id: 'transport', target: $('transport'), title: 'Transport', description: 'Play, stop and record.', }, { id: 'grid', target: $('sequencer'), title: 'The beat grid', description: 'Arrow keys move between cells; Space toggles a hit.', }, { id: 'knob', target: $('knob-bass'), side: 'left', title: 'Bass level', description: 'A slider: ↑ and ↓ change it, and the tour leaves those keys alone.', }, ],});
interface Line { id: number; kind: 'focus' | 'dialog' | 'live'; text: string;}
/** * Approximates what a screen reader conveys: where focus lands (with the element's role and * accessible name) and what the live region announces. Built from the real DOM, not from props. */function useTranscript() { const [lines, setLines] = useState<Line[]>([]); useEffect(() => { let n = 0; const push = (kind: Line['kind'], text: string) => setLines((l) => [...l.slice(-7), { id: n++, kind, text }]);
const label = (el: Element) => { const ids = (attr: string) => (el.getAttribute(attr) ?? '') .split(' ') .map((id) => document.getElementById(id)?.textContent?.trim()) .filter(Boolean) .join(' '); return ( el.getAttribute('aria-label') ?? (ids('aria-labelledby') || el.textContent?.trim() || '') ); }; const onFocus = (event: FocusEvent) => { const el = event.target as Element; if (!el.closest?.('[role=dialog], #heard')) return; const role = el.getAttribute('role') ?? el.tagName.toLowerCase(); if (role === 'dialog') { const description = (el.getAttribute('aria-describedby') ?? '') .split(' ') .map((id) => document.getElementById(id)?.textContent?.trim()) .filter(Boolean) .join(' '); push('dialog', `dialog, ${label(el)}. ${description}`); } else { const value = el.getAttribute('aria-valuetext'); push('focus', `${label(el)}, ${role}${value ? `, ${value}` : ''}`); } }; document.addEventListener('focusin', onFocus);
const live = new MutationObserver(() => { const region = document.querySelector('#heard-announcer [data-tour-announcer]'); const text = region?.textContent?.trim(); if (text) push('live', text); }); const host = document.getElementById('heard-announcer'); if (host) live.observe(host, { childList: true, subtree: true, characterData: true });
const off = tour.on('start', () => setLines([])); return () => { document.removeEventListener('focusin', onFocus); live.disconnect(); off(); }; }, []); return lines;}
const KIND = { focus: 'focus', dialog: 'opens', live: 'polite' } as const;
function Transcript() { const lines = useTranscript(); return ( <div className="flex flex-col gap-1"> <p className="font-semibold text-ink">What a screen reader gets</p> {lines.length === 0 ? ( <p>Start the tour with the keyboard (Tab to “Start tour”, Enter), then use ← → and Tab.</p> ) : ( <ol className="flex flex-col gap-0.5 font-mono"> {lines.map((line) => ( <li key={line.id} className="flex gap-2"> <span className="w-12 shrink-0 text-ink-2">{KIND[line.kind]}</span> <span className="text-ink">{line.text}</span> </li> ))} </ol> )} </div> );}
export function AccessibilityDemo() { return ( <div id="heard-announcer"> <Tour.Root tour={tour}> <DemoFrame title="Heard, not just seen" actions={<StartButton />} footer={<Transcript />}> <LoopworkApp scope="heard" layout="compact" /> </DemoFrame> <TourPopover /> </Tour.Root> </div> );}Semantics
Tour.Contentis arole="dialog", witharia-modalin modal tours.aria-labelledbyandaria-describedbyare wired toTour.TitleandTour.Descriptionautomatically.- The highlighted target gets
aria-describedbypointing to the step, so focusing it reads the explanation. Checklist.Progressis aprogressbar; tour progress is announced by the live region (below).Tour.Indicatorsare buttons with accessible names (“Go to step 3”).
Keyboard
| Key | Action |
|---|---|
| → | Next step (← in RTL). Ignored while typing in inputs. |
| ← | Previous step (→ in RTL). |
| Home / End | First / last visible step. |
| Esc | Close the tour. |
| Tab | Moves through the card; in modal tours focus is trapped inside it. |
Turn them off with keyboardNavigation={false} and closeOnEscape={false} on Tour.Root, or
intercept Escape with onEscapeKeyDown on Tour.Content. Remap them with an object:
keyboardNavigation={{ next: ['ArrowRight', 'j'], prev: ['ArrowLeft', 'k'] }}.
Focus not obscured
WCAG 2.2 asks that the focused element is never hidden by author content (SC 2.4.11). The card is
placed next to its target and flips or shifts to stay on screen without covering it; this is
checked in our end-to-end tests at 200% zoom. If your layout is tight, give Tour.Content a
collisionPadding and keep cards short. For long modal steps, lockScroll on Tour.Root stops
the page from scrolling away underneath.
Focus
- When a step opens, focus moves to the card.
- Modal tours trap focus in the card and make the rest of the page
inert— the highlighted target stays reachable, so interactive steps work with the keyboard too. - When the tour closes, focus returns to the element that had it before (
restoreFocus).
Elements that must stay usable during a modal tour — toasts, chat widgets, devtools — can opt out of
inert with the data-tour-keep attribute.
Screen reader announcements
A polite live region announces each step — “Step 2 of 5” by default. Customize or translate it:
<Tour.Root tour={tour} announce={({ state, step }) => `Passo ${state.progress.current} de ${state.progress.total}: ${step?.meta?.label ?? ''}` }/>Pass announce={false} to disable it.
Motion
Respect prefers-reduced-motion in your CSS animations. The scroll-into-view honors it, and
@awesome-tour/motion swaps movement for instant changes when it’s set.
Your part
- Icon-only buttons (
Tour.Closewith “✕”) have anaria-label. - Every step has a title — it’s the dialog’s accessible name.
- Text and buttons in the card meet contrast requirements.
- Interactive steps don’t rely on pointer-only gestures.
- Modal tours aren’t used for information users must dismiss to work — prefer hotspots for hints.
The library is tested with axe-core in unit tests and in Playwright end-to-end tests.