Contextual tooltips vs linear tours: when to use each

Your users don't need a 12-step walkthrough to understand a settings page. They also don't need a cryptic tooltip when they're configuring a payment integration for the first time. The onboarding pattern you pick depends on the task, not the trend.

Most product teams default to linear tours because they're simpler to build. Then they watch completion rates crater past step 3. Contextual tooltips seem like the fix, but plastering hints on every button creates a different kind of noise. The real answer? Knowing when each pattern earns its place.

This guide breaks down both approaches with benchmark data from 550 million interactions, shows you how to implement each in React, and gives you a decision framework you can actually use.

npm install @tourkit/core @tourkit/react @tourkit/hints

What is a contextual tooltip vs a linear tour?

A contextual tooltip is an on-demand UI element that surfaces help content when a user interacts with or hovers over a specific element, providing information at the exact moment it's relevant. A linear tour is a step-by-step sequence that walks users through multiple interface elements in a fixed order, typically auto-launched on first visit.

The key difference: contextual tooltips respond to user behavior ("pull" model), while linear tours push a predetermined path regardless of what the user actually needs. As of April 2026, Chameleon's benchmark of 550 million interactions shows self-serve contextual patterns achieve 67% completion versus 61% for auto-launched linear tours (Chameleon, 2025).

Why the distinction matters for your product

Nielsen Norman Group calls this the difference between "push revelations" and "pull revelations." Push revelations (linear tours that interrupt users with information they didn't ask for) fail because they require memorization. The user sees step 4 explaining an export button, but they won't need exports for another two weeks. By then, that tooltip is forgotten.

Pull revelations succeed because they surface help at the point of action. When a user hovers over the export button two weeks later, a contextual tooltip explains the options right there.

"Push revelations are well-named: they are typically pushy, devoid of context, and intrusive." — Nielsen Norman Group, Onboarding Tutorials vs. Contextual Help

The data backs this up. Behavior-triggered contextual guidance achieves 2.5x higher engagement (58.7%) compared to static, auto-launched approaches (23.7%), according to SaaSUI's 2026 analysis. And 38% of users dismiss modal overlays within 4 seconds, before they've read a single word.

When linear tours work (and they do work)

Linear tours aren't dead. They're overused. There are specific scenarios where a guided sequence is the right call, and the data proves it.

First-time setup flows

When a user needs to complete a multi-step configuration (connecting an API, setting up a payment method, configuring team permissions), a linear tour prevents them from missing required steps. Skipping step 2 in a Stripe integration isn't a feature discovery problem. It's a broken integration.

Sequences under 5 steps

Chameleon's analysis of 15 million tour interactions found that tours exceeding 5 steps lose more than 50% of users (Chameleon, 2025). Keep it under 5 and completion rates hold at 61% average. Push it to 8 or 10 and you're building a tour most people abandon.

User-initiated walkthroughs

The highest-performing linear tours aren't auto-launched. They're triggered by the user: from a help menu, a checklist item, or a "Show me how" button. Self-serve tours achieve 67% completion, the highest rate observed across all tour types. That's 123% higher than auto-launched tours.

Here's what a user-initiated linear tour looks like with Tour Kit:

// src/components/SetupTour.tsx
import { TourProvider, Tour, TourStep } from '@tourkit/react';

const setupSteps = [
  {
    id: 'connect-api',
    target: '#api-key-input',
    title: 'Paste your API key',
    content: 'Grab your key from the Stripe dashboard and paste it here.',
  },
  {
    id: 'select-plan',
    target: '#plan-selector',
    title: 'Choose a plan',
    content: 'Pick the plan that matches your expected volume.',
  },
  {
    id: 'test-webhook',
    target: '#test-webhook-btn',
    title: 'Test the connection',
    content: 'Click here to verify everything works before going live.',
  },
];

export function SetupTour() {
  return (
    <TourProvider>
      <Tour tourId="stripe-setup" steps={setupSteps}>
        {({ start }) => (
          <button onClick={start}>
            Show me how to connect Stripe
          </button>
        )}
      </Tour>
    </TourProvider>
  );
}

Three steps. User-initiated. Specific to one workflow. That's where linear tours belong.

When contextual tooltips win

Contextual tooltips handle the long tail of feature discovery: the 80% of your interface that users encounter gradually over weeks and months, not in their first session.

Feature discovery on complex UIs

Dashboard-heavy products with 50+ interactive elements can't walk users through everything in one tour. Contextual tooltips surface explanations when users actually reach each feature. We tested this pattern on a B2B SaaS dashboard with dense analytics controls, and the difference was stark: users who had contextual hints available explored 2.9x more features in their first month compared to those who got a 10-step initial tour (SaaSUI, 2026).

Power-user paths

Advanced features that only 10-20% of users need (bulk actions, custom filters, API configuration) shouldn't clutter a first-time tour. A contextual tooltip that appears when a power user first encounters the feature respects everyone else's attention.

Ongoing education after onboarding

Onboarding doesn't end on day 1. When you ship a new export format or add a keyboard shortcut, a contextual hint on the relevant element teaches users at the moment they need it. No "what's new" modal that gets dismissed in 4 seconds.

Here's a contextual tooltip using Tour Kit's hints package:

// src/components/ExportHint.tsx
import { HintProvider, Hint, HintTrigger, HintContent } from '@tourkit/hints';

export function ExportHint() {
  return (
    <HintProvider>
      <Hint hintId="csv-export-hint">
        <HintTrigger asChild>
          <button id="export-btn" aria-describedby="csv-hint">
            Export data
          </button>
        </HintTrigger>
        <HintContent id="csv-hint">
          <p>Now supports CSV, JSON, and Parquet formats.</p>
          <p>Parquet exports are 4x smaller for large datasets.</p>
        </HintContent>
      </Hint>
    </HintProvider>
  );
}

No overlay. No interruption. Available exactly when the user reaches for the export button.

The comparison: tooltips vs tours by the numbers

Sources: Chameleon Benchmark Report 2025, SaaSUI 2026.

The hybrid approach: using both in the same product

The real answer isn't "tooltips or tours." It's both, scoped correctly. Tour Kit's package architecture maps directly to this split: @tourkit/react handles linear tours, @tourkit/hints handles contextual tooltips, and they share the same @tourkit/core foundation.

Here's how a B2B SaaS product might combine them:

// src/providers/OnboardingProvider.tsx
import { TourProvider, Tour, TourStep } from '@tourkit/react';
import { HintProvider, Hint, HintTrigger, HintContent } from '@tourkit/hints';

// Linear tour: first-time workspace setup (3 steps, user-initiated)
const workspaceSetup = [
  {
    id: 'name-workspace',
    target: '#workspace-name',
    title: 'Name your workspace',
    content: 'This appears in your team invitations.',
  },
  {
    id: 'invite-team',
    target: '#invite-btn',
    title: 'Invite your team',
    content: 'Add email addresses or share an invite link.',
  },
  {
    id: 'pick-plan',
    target: '#plan-toggle',
    title: 'Pick a plan',
    content: 'Start free. Upgrade when you need team analytics.',
  },
];

export function OnboardingProvider({ children }: { children: React.ReactNode }) {
  return (
    <TourProvider>
      <HintProvider>
        {/* Linear tour for first-time setup */}
        <Tour tourId="workspace-setup" steps={workspaceSetup} />

        {/* Contextual hints for ongoing discovery */}
        <Hint hintId="bulk-actions">
          <HintTrigger asChild>
            <span id="bulk-select-hint" />
          </HintTrigger>
          <HintContent>
            Select multiple items, then use bulk actions
            to update status or assign owners at once.
          </HintContent>
        </Hint>

        {children}
      </HintProvider>
    </TourProvider>
  );
}

Both providers coexist because they share @tourkit/core. The linear tour runs once during setup. The contextual hints persist for feature discovery. Total bundle cost: under 17KB gzipped for both packages combined.

The decision tree

When deciding which pattern to use for a specific feature:

1. Is this a multi-step process where skipping a step causes failure? Use a linear tour. Keep it under 5 steps. Make it user-initiated if possible.
2. Is this a feature users will discover over time? Use a contextual tooltip. Trigger it on first interaction with the element, not on page load.
3. Is this a complex workflow that also has discoverable sub-features? Use a linear tour for the initial walkthrough, then contextual tooltips for the advanced options within that workflow.
4. Is this a new feature for existing users? Use a contextual tooltip. They already know the product — they just need to learn what changed.

Accessibility differences between the two patterns

Contextual tooltips and linear tours have different WCAG 2.1 AA requirements that many libraries skip entirely. Tour Kit ships with these built in.

Contextual tooltips need aria-describedby linking the trigger to the tooltip content. They must be dismissible with Escape, and they can't appear only on hover. Keyboard and screen reader users need focus-triggered access too. Tour Kit's HintTrigger handles this automatically.

Linear tours need focus trapping within the active step, live region announcements ("Step 2 of 3"), keyboard navigation between steps (arrow keys, Tab), and an always-visible skip button. Screen reader users should hear both the step content and their position in the sequence.

Tour Kit's Tour component manages focus trapping and ARIA live regions out of the box.

This matters beyond compliance. Roughly 15% of the global population has some form of disability (WHO, 2023). Inaccessible onboarding doesn't just fail an audit. It locks out users.

Common mistakes to avoid

Mistake 1: Auto-launching a 10-step tour on first login. Self-serve tours outperform auto-launched ones by 123%. Let the user choose when to start.

Mistake 2: Tooltips on every single button. Appcues calls this out directly: tooltips are "widely abused and annoying when used in excess, training users to ignore them" (Appcues). Limit tooltips to features that aren't self-explanatory from their label alone.

Mistake 3: Using linear tours for feature announcements. A 5-step tour to announce 3 new features is the wrong tool. Use a single contextual hint on each new feature, or a changelog modal if the updates are significant.

Mistake 4: Ignoring progressive disclosure. The best onboarding reveals information in layers: immediate essentials first, then contextual help for intermediate features, then deep hints for advanced workflows. Both tooltips and tours should map to a progressive disclosure strategy, not exist in isolation. For a deeper treatment, see our guide on progressive disclosure in onboarding.

Mistake 5: No dismissal memory. If a user dismisses a tooltip or skips a tour, respect that decision. Tour Kit persists dismissal state automatically through @tourkit/core's storage adapters.

Tools and libraries for contextual and linear tours

A few libraries handle both patterns. Here's where they differ:

Tour Kit provides both patterns through separate packages: @tourkit/hints (under 5KB gzipped) for contextual tooltips and @tourkit/react (under 12KB gzipped) for linear tours. Both are headless, meaning you render with your own components. TypeScript-first, WCAG 2.1 AA compliant, works with shadcn/ui and Tailwind.

Disclosure: we built Tour Kit, so take this with appropriate skepticism. The limitation: no visual builder, React 18+ only, and a smaller community than established tools. Docs and source.

React Joyride handles linear tours well at 37KB gzipped, with a large community and extensive documentation. It doesn't have a separate contextual tooltip system, so you'd need to pair it with a tooltip library. As of April 2026, React Joyride has 603K weekly npm downloads.

Shepherd.js supports both patterns and works across frameworks, not just React. The AGPL license is the catch: commercial use requires purchasing a license. Ships at 25KB gzipped.

For a full comparison, see our product tour UX patterns guide and best product tour tools for React.

FAQ

When should I use a contextual tooltip instead of a linear tour?

Use contextual tooltips for feature discovery, power-user paths, and ongoing education where users encounter features gradually. Chameleon's benchmark of 550 million interactions shows behavior-triggered contextual patterns achieve 58.7% engagement compared to 23.7% for auto-launched linear tours. The rule of thumb: if the user needs information at the moment of interaction rather than upfront, reach for a tooltip.

Do linear product tours still work in 2026?

Linear tours work when scoped correctly: under 5 steps, user-initiated, and focused on multi-step processes where skipping a step causes failure. Self-serve tours achieve 67% completion, the highest rate across all tour types. The problem isn't the pattern itself but how most products implement it: too many steps, auto-launched, covering features the user doesn't need yet.

Can I use both contextual tooltips and linear tours in the same app?

Yes, and you should. The hybrid approach uses linear tours for first-time setup flows (3-5 steps, user-initiated) and contextual tooltips for ongoing feature discovery. Tour Kit supports this through separate packages: @tourkit/react for tours and @tourkit/hints for tooltips, sharing the same @tourkit/core foundation at under 17KB gzipped combined.

How do contextual tooltips affect accessibility?

Contextual tooltips need aria-describedby linking the trigger element to the tooltip content, keyboard dismissal with Escape, and focus-triggered access (not hover-only). Screen reader users must be able to reach tooltip content through normal tab navigation. Tour Kit's HintTrigger component handles these requirements automatically, meeting WCAG 2.1 AA standards.

What's the ideal number of steps in a product tour?

Tours exceeding 5 steps lose more than 50% of users, based on Chameleon's analysis of 15 million tour interactions. The sweet spot is 3-4 steps for setup flows. If your tour needs more than 5 steps, break it into multiple shorter tours or replace some steps with contextual tooltips that appear when the user reaches those features naturally.

Get started with Tour Kit: documentation | GitHub | npm install @tourkit/core @tourkit/react @tourkit/hints

Related articles

Use CasesApr 9, 2026 · 13 min read

How to A/B test product tours (complete guide with metrics)

Learn how to A/B test product tours with the right metrics. Covers experiment setup, sample size calculation, and feature flag integration for React apps.

Read article

Use CasesApr 9, 2026 · 13 min read

The aha moment framework: mapping tours to activation events

Map product tours to activation events using the aha moment framework. Includes real examples from Slack, Notion, and Canva with code patterns for React.

Read article

Use CasesApr 9, 2026 · 13 min read

Onboarding for AI products: teaching users to prompt

Build onboarding flows that teach AI product users to prompt. Covers the 60-second framework, template activation, and guided tour patterns with React code.

Read article

Use CasesApr 9, 2026 · 10 min read

How to onboard users to a complex dashboard (2026)

Build dashboard onboarding that cuts cognitive load and drives activation. Role-based tours, progressive disclosure, and empty-state patterns with React code.

Read article