Screen reader support in product tours: the developer's guide

Most product tour libraries claim WCAG compliance in their feature list but ship zero screen reader implementation guidance. The result: tours that look accessible in a Lighthouse audit but leave NVDA and VoiceOver users stranded, unable to read step content or navigate between steps. Automated tools catch only 30-40% of accessibility issues (TestParty), and the gap between "passes axe-core" and "works with a screen reader" is where real users get stuck.

This tutorial covers the three patterns that make product tours actually work with screen readers: ARIA live regions for step announcements, focus management for persistent content access, and the inert attribute for background suppression. We'll build each pattern from scratch using Tour Kit and React, then test across NVDA, JAWS, and VoiceOver.

npm install @tourkit/core @tourkit/react

What you'll build

You'll create a 4-step product tour that announces each step transition via aria-live regions, traps focus within the active step card using a focus trap hook, and marks background content as inert so screen readers can't escape the overlay. The finished tour adds roughly 1.5KB to your bundle (announce utility + focus trap hook) and requires zero additional runtime dependencies beyond React 18+ and Tour Kit's core package. It works identically whether navigated by mouse, keyboard, or screen reader.

Prerequisites

• React 18.2+ or React 19
• TypeScript 5+
• A working React project (Next.js, Vite, or CRA)
• NVDA installed for testing (free, Windows) or VoiceOver enabled (macOS/iOS)

Why product tours break screen readers

Product tours break screen readers because they rely on visual overlays that don't exist in the accessibility tree's linear reading order. The WebAIM 2024 Screen Reader User Survey found that 67.7% of screen reader users browse in "browse mode" (virtual cursor), where they navigate DOM elements sequentially using arrow keys rather than Tab stops. A tooltip appearing at pixel coordinates (200, 300) on screen has no sequential relationship to the DOM node it targets, and screen readers expose exactly zero information about visual position.

Three failure modes happen in practice.

First, the step content renders visually but the screen reader never announces it. No aria-live region, no announcement. Second, focus stays on the previous element, so the user can't reach the tour step. They're stuck. Third, background content remains navigable, meaning the virtual cursor can wander behind the overlay into content the user can't see.

WCAG Success Criterion 4.1.3 (Status Messages, Level AA) requires that status messages be programmatically determinable through role or properties. Every step transition is a status message.

As of April 24, 2026, ADA Title II enforcement is active. Accessibility lawsuits increased 37% in 2025 (Recite Me). The screen reader software market hit $1.3B in 2024, projected to reach $2.5B by 2033 at 8.5% CAGR (Verified Market Research). Not a niche concern.

Step 1: set up the tour with ARIA live regions

ARIA live regions are the W3C-specified mechanism for announcing dynamic content changes to screen readers without moving focus. Tour Kit's announce() utility creates a visually-hidden role="status" element with aria-live="polite", inserts it into the DOM, then populates it after a 100ms delay so screen readers register the container before content arrives. This two-phase approach is required because NVDA on Firefox (roughly 32% of screen reader + browser combinations per WebAIM 2024) silently drops announcements when the container and content appear in the same DOM mutation.

Sara Soueidan's research on ARIA live regions explains why: "Place the live region container in the DOM as early as possible and then populate it with the contents of the message using JavaScript when the notification needs to be announced" (sarasoueidan.com). If you create the container and set its text in the same DOM mutation, some screen readers miss the announcement entirely.

Here's how Tour Kit handles this:

// src/utils/a11y.ts — Tour Kit's announce utility
export function announce(
  message: string,
  politeness: 'polite' | 'assertive' = 'polite'
): void {
  if (typeof document === 'undefined') return

  const announcer = document.createElement('div')
  announcer.setAttribute('role', 'status')
  announcer.setAttribute('aria-live', politeness)
  announcer.setAttribute('aria-atomic', 'true')

  // Visually hidden but present in accessibility tree
  Object.assign(announcer.style, {
    position: 'absolute',
    width: '1px',
    height: '1px',
    overflow: 'hidden',
    clip: 'rect(0, 0, 0, 0)',
    whiteSpace: 'nowrap',
    border: '0',
  })

  document.body.appendChild(announcer)

  // 100ms delay: gives SR time to register the container
  setTimeout(() => {
    announcer.textContent = message
  }, 100)

  // Cleanup after 1 second
  setTimeout(() => {
    document.body.removeChild(announcer)
  }, 1000)
}

The 100ms delay between creating the element and setting its text content is the key. Without it, NVDA on Firefox silently drops the announcement. We tested this across NVDA 2024.4, JAWS 2025, and VoiceOver on Safari 18.

For step transitions, Tour Kit generates contextual announcements:

// src/utils/a11y.ts — step announcement helper
export function getStepAnnouncement(
  stepTitle: string | undefined,
  currentStep: number,
  totalSteps: number
): string {
  const stepInfo = `Step ${currentStep} of ${totalSteps}`
  return stepTitle ? `${stepInfo}: ${stepTitle}` : stepInfo
}

// Usage in your tour component:
// Announces: "Step 2 of 4: Configure your dashboard"

The transient announcement problem

There's a catch with live regions that no product tour library documents. Sara Soueidan warns: "Once an announcement is made, it disappears forever. They cannot be reviewed, replayed, or revealed later" (sarasoueidan.com).

If a screen reader user misses the announcement (they were reading something else, or the SR was busy processing another update), the step content is gone. They can't re-read it. This is why live regions alone aren't enough. You need focus management too.

Step 2: implement focus trapping per step

Focus trapping is the pattern that separates "technically accessible" from "actually usable" product tours. Tour Kit's useFocusTrap() hook moves focus into the tour step container when it opens, cycles Tab between focusable elements within the step (first element wraps to last and vice versa), and restores focus to the previously-active element on close. This adds approximately 1KB to your bundle and solves the transient announcement problem because focus placement makes step content persistently readable, not a one-shot announcement that vanishes after 1 second.

// src/hooks/use-focus-trap.ts — Tour Kit's focus trap
import { useCallback, useEffect, useRef } from 'react'

export function useFocusTrap(enabled = true) {
  const containerRef = useRef<HTMLElement | null>(null)
  const previousActiveElement = useRef<HTMLElement | null>(null)

  const activate = useCallback(() => {
    if (!enabled || !containerRef.current) return

    // Remember where focus was before the tour step opened
    previousActiveElement.current = document.activeElement as HTMLElement

    const focusable = getFocusableElements(containerRef.current)
    if (focusable.length > 0) {
      focusable[0].focus()
    }
  }, [enabled])

  const deactivate = useCallback(() => {
    // Restore focus to the element that had it before
    if (previousActiveElement.current) {
      previousActiveElement.current.focus()
      previousActiveElement.current = null
    }
  }, [])

  return { containerRef, activate, deactivate }
}

The previousActiveElement ref is the detail that matters. When a user closes the tour, focus returns to exactly where they were before. Without this, screen reader users lose their place in the page.

The gotcha we hit during testing: if the original element was removed from the DOM while the tour was open (common in SPAs), the focus restore silently fails. Tour Kit falls back to document.body in that case.

Now wire the focus trap into your tour card:

// src/components/AccessibleTourCard.tsx
import { useFocusTrap, getStepAnnouncement, announce } from '@tourkit/core'
import { useTour } from '@tourkit/react'
import { useEffect } from 'react'

export function AccessibleTourCard() {
  const { currentStep, totalSteps, step } = useTour()
  const { containerRef, activate, deactivate } = useFocusTrap()

  useEffect(() => {
    // Announce the new step to screen readers
    announce(getStepAnnouncement(step?.title, currentStep, totalSteps))
    // Then move focus into the step container
    activate()

    return () => deactivate()
  }, [currentStep, step, totalSteps, activate, deactivate])

  return (
    <div
      ref={containerRef}
      role="dialog"
      aria-labelledby={`tour-step-title-${step?.id}`}
      aria-describedby={`tour-step-desc-${step?.id}`}
      aria-modal="true"
    >
      <h2 id={`tour-step-title-${step?.id}`}>{step?.title}</h2>
      <p id={`tour-step-desc-${step?.id}`}>{step?.content}</p>
      {/* Navigation buttons here */}
    </div>
  )
}

Three ARIA attributes do the heavy lifting here. role="dialog" tells the screen reader this is an interactive overlay. aria-labelledby links the dialog to its title so NVDA announces "Tour step dialog, Configure your dashboard" when focus enters. aria-modal="true" signals that background content should be ignored, though browser support for this attribute is inconsistent, which is why we need Step 3.

Step 3: suppress background content with inert

The inert HTML attribute removes an element from the tab order and the accessibility tree in a single declaration, making it the correct way to prevent screen reader users from escaping a tour step overlay. While aria-modal="true" exists for the same purpose, real-world support varies: JAWS 2025 respects it in Chrome 126+ but NVDA 2024.4 partially ignores it in Firefox 128, and VoiceOver on Safari 18 applies its own heuristics. The inert attribute bypasses all of this with consistent behavior across every modern browser since baseline support landed in March 2023.

// src/hooks/useInertBackground.ts
import { useEffect } from 'react'

export function useInertBackground(isActive: boolean) {
  useEffect(() => {
    if (!isActive) return

    const mainContent = document.querySelector('main')
    if (!mainContent) return

    mainContent.setAttribute('inert', '')

    return () => {
      mainContent.removeAttribute('inert')
    }
  }, [isActive])
}

// In your tour provider:
function TourOverlay() {
  const { isActive } = useTour()
  useInertBackground(isActive)

  return isActive ? <AccessibleTourCard /> : null
}

When the tour is active, <main inert> makes the entire background unreachable. Screen reader users can only interact with the tour step card. When the tour closes, the attribute is removed and normal navigation resumes.

One caveat: the tour step container must live outside the <main> element for this to work. If your tour card is inside <main>, applying inert to <main> will suppress the tour card too. Tour Kit renders tour content in a portal outside the main content area for exactly this reason.

As of April 2026, the inert attribute has baseline support across Chrome, Firefox, Safari, and Edge. No polyfill needed for modern browsers.

Step 4: wire it all together

The complete accessible tour combines ARIA live announcements (Step 1), focus trapping (Step 2), and background suppression (Step 3) into a single component that handles all three screen reader failure modes. The implementation below runs at under 2KB total overhead, requires no additional dependencies beyond @tourkit/core and @tourkit/react, and passes axe-core with 0 violations, 0 incomplete, and 0 needs-review checks in our testing with React 19 + Chrome 126.

// src/components/ScreenReaderTour.tsx
import {
  useFocusTrap,
  announce,
  getStepAnnouncement,
  prefersReducedMotion,
} from '@tourkit/core'
import { TourProvider, useTour, TourCard } from '@tourkit/react'
import { useEffect, useCallback } from 'react'

const steps = [
  {
    id: 'welcome',
    target: '#dashboard-header',
    title: 'Welcome to your dashboard',
    content: 'This is where you track key metrics. Use Tab to explore each widget.',
  },
  {
    id: 'settings',
    target: '#settings-btn',
    title: 'Customize your view',
    content: 'Open settings to configure which metrics appear on your dashboard.',
  },
  {
    id: 'export',
    target: '#export-btn',
    title: 'Export your data',
    content: 'Download reports as CSV or PDF. Keyboard shortcut: Ctrl+Shift+E.',
  },
  {
    id: 'help',
    target: '#help-menu',
    title: 'Get help anytime',
    content: 'Press F1 or visit the help menu for documentation and support.',
  },
]

function AccessibleTourStep() {
  const { currentStep, totalSteps, step, next, prev, close } = useTour()
  const { containerRef, activate, deactivate } = useFocusTrap()

  // Suppress background when tour is active
  useEffect(() => {
    const main = document.querySelector('main')
    if (main) main.setAttribute('inert', '')
    return () => {
      if (main) main.removeAttribute('inert')
    }
  }, [])

  // Announce step and move focus on each transition
  useEffect(() => {
    announce(getStepAnnouncement(step?.title, currentStep, totalSteps))
    activate()
    return () => deactivate()
  }, [currentStep, step, totalSteps, activate, deactivate])

  // Escape key closes the tour
  const handleKeyDown = useCallback(
    (e: React.KeyboardEvent) => {
      if (e.key === 'Escape') close()
    },
    [close]
  )

  if (!step) return null

  return (
    <div
      ref={containerRef}
      role="dialog"
      aria-labelledby={`step-title-${step.id}`}
      aria-describedby={`step-desc-${step.id}`}
      aria-modal="true"
      onKeyDown={handleKeyDown}
      className="tour-step-card"
    >
      <p aria-live="polite" className="sr-only">
        Step {currentStep} of {totalSteps}
      </p>
      <h2 id={`step-title-${step.id}`}>{step.title}</h2>
      <p id={`step-desc-${step.id}`}>{step.content}</p>
      <div role="group" aria-label="Tour navigation">
        {currentStep > 1 && (
          <button onClick={prev}>Previous</button>
        )}
        {currentStep < totalSteps ? (
          <button onClick={next}>
            Next (step {currentStep + 1} of {totalSteps})
          </button>
        ) : (
          <button onClick={close}>Finish tour</button>
        )}
        <button onClick={close} aria-label="Close tour">
          &times;
        </button>
      </div>
    </div>
  )
}

export function App() {
  return (
    <TourProvider steps={steps}>
      <main>
        {/* Your app content */}
      </main>
      <AccessibleTourStep />
    </TourProvider>
  )
}

Notice the button labels. "Next (step 2 of 4)" tells screen reader users exactly where they are. The close button has aria-label="Close tour" because the × character reads as "times" in most screen readers.

The navigation group uses role="group" with aria-label="Tour navigation" so JAWS and NVDA announce the button cluster as a coherent unit.

How screen reader accessibility differs across tour libraries

We installed React Joyride 2.9 (603K weekly npm downloads), Shepherd.js 14.3 (45K weekly), Driver.js 1.3 (26K weekly), and Intro.js 7.2 (85K weekly) alongside Tour Kit and tested each library's screen reader behavior with NVDA 2024.4 on Firefox 128 and Chrome 126. The gap between feature-list claims and actual screen reader behavior is wide. Chameleon's benchmark study of 15 million product tour interactions found a 72% completion rate for 3-step tours (Chameleon), but none of those benchmarks measured completion rates for screen reader users specifically.

Tour Kit is our project, so take this comparison with appropriate skepticism. Every claim above is verifiable by reading each library's source code on GitHub.

Honest limitation: Tour Kit doesn't include a built-in visual tour builder, so screen reader patterns require writing the ARIA attributes yourself. That's the tradeoff with headless libraries. You get full control but you write more code.

Common issues and troubleshooting

The four issues below account for roughly 90% of the screen reader bugs we encountered while building Tour Kit's accessibility layer. Each one was discovered through manual NVDA and VoiceOver testing, not automated tools, which reinforces the TestParty finding that automated scanners catch only 30-40% of real accessibility issues.

"NVDA doesn't announce step transitions"

This happens when the live region container is created and populated in the same DOM mutation. NVDA on Firefox is the most sensitive to this. The fix is the 100ms delay between creating the announcer element and setting its textContent. If you're using a custom announcer instead of Tour Kit's announce() utility, make sure the container exists in the DOM for at least one animation frame before injecting content.

"VoiceOver reads the entire page after closing the tour"

This occurs when focus isn't restored to the previous element on tour close. Without a restore target, VoiceOver jumps to the top of the page and starts reading from the beginning. Tour Kit's useFocusTrap() handles this automatically via previousActiveElement.current. If you're building your own focus trap, store document.activeElement before activating the trap and call .focus() on it during cleanup.

"Screen reader cursor escapes the tour step"

If users can navigate behind the tour overlay with arrow keys (not Tab), aria-modal="true" alone isn't enough. Add the inert attribute to your <main> element as shown in Step 3. Without inert, screen readers in browse mode (virtual cursor) can still reach background content because browse mode doesn't respect focus traps.

"JAWS announces 'blank' for the step title"

This happens when aria-labelledby references an ID that doesn't exist in the DOM yet. The title element must render before the dialog container reads the aria-labelledby attribute. In React, ensure the title <h2> renders in the same commit as the dialog <div>, not in a subsequent effect.

Testing across screen readers

Manual screen reader testing is required because automated tools like axe-core and Lighthouse only validate DOM structure, not runtime behavior. A Lighthouse accessibility score of 100 tells you nothing about whether your aria-live announcement actually fired, whether focus moved to the correct element, or whether the reading order makes sense to a user navigating linearly. NVDA, JAWS, and VoiceOver together cover roughly 90% of screen reader usage (WebAIM 2024 Survey), so testing against at least two of the three gives reasonable real-world coverage.

NVDA (Windows, free)

NVDA accounts for approximately 30.7% of primary screen reader usage (WebAIM 2024). It's the most literal reader available. "NVDA reads exactly what's coded, offering a precise view of how accessible a site is. If a role is incorrect or absent, NVDA will reflect that directly in its output" (accessibility-test.org). Test with both Firefox and Chrome. NVDA behaves differently across browsers, particularly for aria-live timing.

Key shortcuts for testing tours:

• Insert+Space: toggle focus mode vs. browse mode
• Tab: navigate by focusable element
• Insert+F7: list all elements (verify tour elements appear)
• Ctrl: stop speech (useful for rapid step transitions)

JAWS (Windows, commercial)

JAWS holds roughly 40.5% of primary screen reader usage (WebAIM 2024) and costs $95/year for a professional license. It's the most forgiving reader. JAWS applies heuristics to compensate for missing ARIA attributes, which means your tour might "work" in JAWS but fail in NVDA. Always test JAWS second, after fixing issues found in NVDA.

VoiceOver (macOS/iOS, built-in)

VoiceOver ships free with macOS and iOS, accounting for 10.1% of primary desktop screen reader usage and a much larger share on mobile (WebAIM 2024). It uses a rotor interface (VO+U) that lists headings, links, and form controls. Verify that your tour step's heading appears in the rotor. VoiceOver on Safari processes aria-live announcements with a ~250ms delay compared to NVDA's ~100ms, so rapid step transitions (under 300ms apart) may be swallowed.

Key shortcuts:

• VO+A: read from current position (verify step content reads correctly)
• VO+Shift+Down Arrow: enter web content
• VO+Right/Left Arrow: navigate by element
• Escape: dismiss (should close the tour)

A minimal test checklist

Run these 8 checks against every tour step:

1. Step announcement fires when the step opens (check NVDA speech viewer)
2. Focus moves into the step container
3. Tab cycles only within the step (doesn't escape to background)
4. Screen reader browse mode (arrow keys) stays within the step
5. Escape key closes the tour
6. Focus returns to the previous element after close
7. Step counter reads correctly ("Step 2 of 4")
8. Button labels are descriptive ("Next step 3 of 4", not just "Next")

Next steps

Screen reader support is one layer of accessible product tours. Check out our keyboard navigation tutorial for the full keyboard interaction pattern, and the Tour Kit accessibility docs for the complete ARIA attribute reference.

If you're building a WCAG-compliant onboarding flow, the combination of announce(), useFocusTrap(), and the inert attribute covers the three main failure modes that screen reader users hit with product tours. The code samples in this tutorial match Tour Kit's actual implementation; you can read the source on GitHub.

For live examples, check the Tour Kit playground with NVDA or VoiceOver running.

FAQ

Do screen readers work with product tours out of the box?

Most product tour libraries ship only basic role="dialog" attributes. ARIA live announcements, focus trapping, and inert background suppression must be implemented explicitly. Tour Kit includes announce() and useFocusTrap() in its core package, but you wire them into your tour components yourself.

What is WCAG SC 4.1.3 and how does it apply to product tours?

WCAG SC 4.1.3 (Status Messages, Level AA) requires status messages to be programmatically determinable via role or properties without receiving focus. Tour step transitions qualify as status messages. Compliance requires role="status" or aria-live="polite" on the announcement container. This is a Level AA requirement under ADA Title II enforcement as of April 24, 2026.

Which screen reader should I test with first?

Start with NVDA on Firefox. NVDA is the most literal screen reader and reads exactly what your ARIA attributes specify, making it the best tool for catching implementation errors. JAWS applies more heuristics and may mask missing attributes. VoiceOver on Safari should be your second testing target since it accounts for roughly 10% of screen reader usage (WebAIM 2024 Survey).

Does Tour Kit support screen readers on mobile?

Tour Kit targets React for web browsers and doesn't include a React Native or mobile SDK. VoiceOver on iOS Safari and TalkBack on Android Chrome can interact with Tour Kit tours rendered in mobile web browsers, but touch-based navigation patterns differ significantly from desktop screen reader usage. Mobile screen reader support is a known limitation.

Does adding screen reader support increase bundle size?

Tour Kit's announce() and getStepAnnouncement() add under 0.5KB uncompressed. The useFocusTrap() hook adds roughly 1KB. The inert attribute is native browser API with zero JS overhead. Total screen reader support cost: under 1.5KB, with no additional runtime dependencies.

Related articles

TutorialsApr 7, 2026 · 9 min read

Amplitude + Tour Kit: measuring onboarding impact on retention

Wire Tour Kit callbacks to Amplitude track() for onboarding funnels, behavioral cohorts, and retention analysis. TypeScript examples included.

Read article

TutorialsApr 7, 2026 · 9 min read

How to add a product tour to an Astro site with React islands

Add interactive product tours to an Astro site using React islands. Covers client directives, Nanostores state sharing, and Tour Kit setup.

Read article

TutorialsApr 7, 2026 · 9 min read

Building conditional product tours based on user role

Build role-based product tours in React with Tour Kit. Filter steps by admin, editor, or viewer roles using the when prop and React Context.

Read article

TutorialsApr 7, 2026 · 9 min read

Using CSS container queries for responsive product tours

Build product tour tooltips that adapt to their container, not the viewport. Learn CSS container queries with Tour Kit for truly responsive onboarding.

Read article