The product tour is dead. Long live the headless tour.

Seventy-eight percent of users abandon traditional product tours before reaching the final step. Not because onboarding is a bad idea, but because the tools we've been using to build it are fundamentally broken. The product tour as we know it, a linear sequence of tooltips glued to DOM elements with a third-party script, has run its course.

What comes next isn't the absence of guided onboarding. It's a different architecture for delivering it: headless, composable, owned by the team that ships the product. The same shift that happened to UI components (Radix, shadcn/ui, React Aria) is coming for product tours. And it's overdue.

npm install @tourkit/core @tourkit/react

The problem: product tours that nobody finishes

Product tours fail at a rate that should embarrass the entire onboarding industry. A Pendo study across 847 B2B SaaS apps found that tours with more than five steps see 67% abandonment. Push past eight steps and that number climbs to 84%. The steepest drop-off happens at steps three and four, where 48% of users bail (SaaS Factor, 2026).

These aren't edge cases. They're the norm.

The problem isn't that users don't want help. It's that traditional tours commit three architectural sins simultaneously: they force a linear path through a non-linear product, they render UI that clashes with the app's design system, and they load JavaScript from a third-party domain that the engineering team doesn't control.

76.3% of product tooltips are dismissed within three seconds. Not read. Dismissed. Users have developed what the UX research community calls "guidance fatigue": an automatic dismissal reflex triggered by anything that looks like a canned walkthrough. And 23% of SaaS churn traces back to bad onboarding experiences (Formbricks, 2026).

As the Smashing Magazine guide on product tours put it: "Users are usually not keen on long introductory tutorials. They become anxious when they have to ingest a lot of information before being able to use a feature" (Smashing Magazine).

The industry's response? Build more features on top of the same broken architecture. Add checklists, NPS surveys, resource centers. None of it addresses the structural problem: the tour is a foreign object inside your app.

The argument: headless fixes the root cause

The headless UI pattern separates a component's logic and state management from its visual rendering. Martin Fowler's engineering blog defines it precisely: "A headless component extracts all non-visual logic and state management, separating the brain of a component from its looks" (Martin Fowler, Juntao QIU). This pattern powers Radix UI, React Aria, Headless UI, Downshift, and the fastest-growing React component libraries of the past three years.

Headless UI adoption grew 70% in 2025 alone (Builder.io). shadcn/ui is the top pick for new React projects in 2026. Developers have voted with their installs: they want logic they can trust and UI they can own.

But nobody has applied this model to product tours. Every tour library on npm bundles its own rendering layer. React Joyride ships inline styles you can't override without !important. Shepherd.js forces you out of JSX and into HTML template strings. Intro.js renders buttons as anchor tags, violating basic accessibility semantics.

A headless tour library works differently:

// src/components/OnboardingTour.tsx
import { useTour, useStep, TourProvider } from '@tourkit/react';

function TourTooltip() {
  const { currentStep, next, prev, isLastStep } = useTour();
  const { target, content } = useStep();

  // Your design system. Your components. Your rules.
  return (
    <Card className="max-w-sm shadow-lg">
      <CardContent className="p-4">
        <p className="text-sm text-muted-foreground">{content}</p>
        <div className="flex justify-between mt-4">
          <Button variant="ghost" onClick={prev}>Back</Button>
          <Button onClick={next}>
            {isLastStep ? 'Done' : 'Next'}
          </Button>
        </div>
      </CardContent>
    </Card>
  );
}

The hooks handle positioning, scroll management, element targeting, keyboard navigation, and ARIA attributes. You write the JSX. Your <Card> and <Button> are the same ones used everywhere else in your app. No style conflicts. No z-index wars. No design system regression when a vendor pushes an update you didn't ask for.

What breaks with traditional tour libraries

The React ecosystem has moved faster than its tour libraries. Here's how the major options compare as of April 2026:

As of April 2026, React Joyride hasn't had a stable release in nine months. Its React 19 compatibility exists only on an unstable next branch. Shepherd.js now requires a commercial license for non-open-source projects. Sandro Roth's evaluation of tour libraries concluded: "Finding a good tour library is challenging. Incompatibility with React 19 and poor accessibility are dealbreakers" (sandroroth.com).

The aggregate finding from multiple 2025-2026 comparison articles is blunt: nothing modern, free, and React-native exists in the traditional tour library space.

Why headless wins long-term

Three structural advantages compound over time.

Your design system stays intact. A headless tour library renders nothing. It provides hooks, context, and positioning logic. Your tooltip is your <Popover>. Your progress indicator is your <Progress>. When your design team updates the border radius from 8px to 12px, every tour step updates automatically because it's the same component.

Accessibility comes from the right layer. Traditional tour libraries bolt on ARIA attributes as an afterthought. A headless approach pushes accessibility into the hook layer: focus trapping, keyboard navigation, aria-live announcements, and prefers-reduced-motion support all happen before your JSX enters the picture. Intro.js implements tour step buttons as <a> tags. That's not a bug to fix; it's an architecture that can't be fixed.

Bundle size stays under control. React Joyride ships at ~37KB gzipped. Tour Kit's core is ~8KB. When the tour library doesn't include a rendering layer, styles, or animation system, there's less code to ship. For a feature that most users encounter once, during their first session, that 29KB difference matters.

The counterargument: why someone might disagree

The headless approach is not a universal fix. It shifts work from CSS overrides to component authoring, removes non-technical access, and trades a large established community for a smaller one. Three objections deserve honest engagement.

"Headless means more setup work." True. A headless tour library doesn't ship a pre-built tooltip. You write the component, or copy one from a starter template. If your team doesn't have a design system (no <Card>, no <Button>, no <Popover>), the upfront cost is real. Developers sometimes underestimate the maintenance surface area they're signing up for (Webflow Blog).

But most teams using React in 2026 already have these components. shadcn/ui ships them for free. A 15-line tooltip component is a one-time cost that pays for itself the first time you need to match a design update without fighting vendor CSS.

"Non-technical teams can't edit tours." This one sticks. Product managers using Appcues or Userpilot can create and modify tours without filing a Jira ticket. A headless library puts tour authoring back in developer hands. For teams where the PM owns the onboarding flow, that's a regression.

We built Tour Kit for developer-led teams — companies where the people shipping features also ship the onboarding for those features. If your org has a dedicated non-technical onboarding manager, a no-code platform might genuinely be the better call. We're not going to pretend otherwise.

"Established libraries have bigger communities." React Joyride has roughly 400K weekly npm downloads. That's a real ecosystem with Stack Overflow answers, blog posts, and battle-tested edge cases. Tour Kit is newer and smaller.

But community size and code quality don't always correlate. React Joyride has unresolved bugs dating back to August 2020. Its spotlight breaks in dark mode. It doesn't support React 19 in a stable release. A large community that can't fix its React 19 compatibility in over a year isn't necessarily safer than a smaller project that ships React 19 support from day one.

What this means for React teams

The product tour isn't dead as a concept. Guided onboarding is still how users learn complex software, and it will remain essential for any product with more than three features. What's dying is the specific implementation model that has dominated the space for a decade. Three things are happening simultaneously in 2026:

React 19 broke the old guard. Both React Joyride and Shepherd's React wrapper are incompatible with React 19 in their stable releases. Teams upgrading their apps have zero well-maintained traditional tour libraries to choose from. This isn't a feature gap. It's a compatibility crisis.

Headless architecture went mainstream. shadcn/ui, Radix, React Aria, Ark UI. Developers have accepted the headless model for buttons, dialogs, dropdowns, and accordions. The only category still stuck in the monolithic era is product tours.

SaaS onboarding vendors crossed a pricing line. Appcues starts at $249/month with essential features locked behind higher tiers. Teams that started with a free trial find themselves paying thousands per year for functionality that amounts to positioning tooltips near DOM elements. Developer frustration with vendor pricing is documented across Reddit, G2 reviews, and the growing "build vs buy" conversation in SaaS communities.

The convergence creates an opening for a different approach. Not "no tours," but better tours. Tours that render with your components, respect your theme, pass WCAG audits, support React 19, and don't charge per monthly active user.

What we'd do differently

Choosing between a no-code platform, a headless library, and building from scratch depends on who owns the onboarding workflow, whether your team has an existing design system, and how much you're willing to pay per month for tooltip positioning. Here's the decision framework we'd use:

Use a no-code platform (Appcues, Userpilot, Chameleon) if: your onboarding is owned by a non-technical team, you need to ship tours this week without developer involvement, and you can absorb per-MAU pricing as the business scales.

Use a headless tour library if: your engineering team owns the onboarding experience, you have an existing design system, you need React 19 compatibility, accessibility compliance matters, and you want a one-time cost instead of recurring SaaS fees.

Build from scratch if: you only need a single 3-step tooltip flow and don't want any dependency. But budget 40-80 hours of engineering time for scroll handling, focus management, positioning, resize observers, and keyboard navigation. We built Tour Kit because we went down this road once and decided never to do it again.

We built Tour Kit as an open-source, headless-first tour library. The core is MIT licensed, under 8KB gzipped, with zero runtime dependencies. React 18 and 19 both work. Ten composable packages (install only what you need). Full disclosure: this is our project, so take the recommendation with appropriate skepticism. Every claim is verifiable against npm, GitHub, and bundlephobia.

That said, Tour Kit doesn't have a visual builder. It requires React developers. The community is smaller than React Joyride's. If those are dealbreakers for your team, they're legitimate dealbreakers.

Get started at usertourkit.com or browse the GitHub repo.

FAQ

Is the headless product tour approach harder to set up than React Joyride?

Tour Kit requires writing a tooltip component (roughly 15 lines of JSX) using your existing design system. If your app already has a <Card> component, setup takes about 10 minutes. React Joyride ships a pre-built tooltip with inline styles that most teams end up overriding anyway, which creates design debt that compounds with every future style change.

Can a headless tour library work with any CSS framework?

Yes. Because a headless tour library renders no UI of its own, it works with Tailwind CSS, CSS Modules, styled-components, Emotion, vanilla CSS, or no CSS framework at all. The hooks provide positioning coordinates and state; you write the JSX and apply whatever styling approach your project uses. There's nothing to override because there are no default styles.

What's the performance difference between headless and styled tour libraries?

Tour Kit's core ships at approximately 8KB gzipped with zero runtime dependencies. React Joyride ships at approximately 37KB gzipped. For a feature most users encounter once during their first session, that 29KB difference directly affects Time to Interactive on the critical first load. Tour Kit's headless architecture also avoids style injection, eliminating the layout recalculation that styled libraries trigger on mount.

Do headless tours pass accessibility audits?

Tour Kit ships WCAG 2.1 AA compliant out of the box. Focus trapping, keyboard navigation (arrow keys and Escape), aria-live region announcements, and prefers-reduced-motion support are built into the hook layer, not the component layer. Traditional tour libraries like Intro.js implement tour step buttons as <a> tags rather than <button> elements, which is a semantic HTML violation that fails automated accessibility scans.

Who should NOT use a headless tour library?

Teams where product managers or marketers own the onboarding flow without developer involvement. No-code platforms like Appcues and Userpilot let non-engineers create and edit tours through a visual builder. A headless library puts tour authoring in code, so every change goes through the development workflow. If your iteration speed depends on skipping the deploy cycle, a headless library will slow you down.

Related articles

Thought LeadershipApr 11, 2026 · 11 min read

How AI will change product onboarding (and what won't change)

AI will personalize onboarding timing, content, and sequencing. But trust, accessibility, and user control still require human decisions. A developer's take.

Read article

Thought LeadershipApr 11, 2026 · 8 min read

Why the best onboarding software in 2026 is a React library

Code-first React libraries beat SaaS onboarding platforms on cost, performance, and control. Pricing data, bundle sizes, and architecture compared.

Read article

Thought LeadershipApr 11, 2026 · 7 min read

GitHub stars don't pay the bills (but they help)

A solo developer's honest look at what GitHub stars actually do for an open-source library. Real numbers on the gap between stars and revenue.

Read article

Thought LeadershipApr 11, 2026 · 10 min read

From 0 to 1000 GitHub stars: the Tour Kit playbook

How I grew a React product tour library from zero to its first 1,000 GitHub stars as a solo developer. Real tactics, real numbers, no paid ads.

Read article