Skip to content
awesome-tour

Type to search every page.

    BAccessibilityContents

    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.

    Heard, not just seen
    Loopworknight-drive.lwp
    001.1.1

    Beat A

    16 steps · drums
    Kick
    Snare
    Hat
    Clap

    Mixer

    4 channels
    Drums
    80%
    Bass
    35%
    Keys
    60%
    Vox
    50%

    What a screen reader gets

    Start the tour with the keyboard (Tab to “Start tour”, Enter), then use ← → and Tab.

    AccessibilityDemo.tsx
    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.Content is a role="dialog", with aria-modal in modal tours.
    • aria-labelledby and aria-describedby are wired to Tour.Title and Tour.Description automatically.
    • The highlighted target gets aria-describedby pointing to the step, so focusing it reads the explanation.
    • Checklist.Progress is a progressbar; tour progress is announced by the live region (below).
    • Tour.Indicators are 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.Close with “✕”) have an aria-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.