Product tours that wear
your design system

All the logic — targeting, positioning, animated spotlight, keyboard navigation — none of the opinions. Restyle it with CSS variables, class names, or replace every component with your own.

Why another tour library?

Most tour packages ship their own look and fight your theme. This one is headless: it does the hard parts and stays out of your stylesheet.

Size matters

Every kilobyte you ship is loading time your users pay for a feature they see once.

Sizes measured via bundlephobia, September 2026. “Core” excludes the Floating UI positioning engine (shared with many popover/tooltip libraries, so you may already ship it).

Documentation

The essentials — the full API reference lives in the README.

1 · Quick start

import { TourProvider, useTour, type TourStep } from "react-headless-tour";

const steps: TourStep[] = [
  { title: "Welcome 👋", content: "No target = centered modal step." },
  { target: "#stats", title: "Your metrics", content: "At a glance." },
  { target: "#new", title: "Create one", placement: "left", interactable: true },
];

function StartButton() {
  const { start } = useTour();
  return <button onClick={() => start()}>Start tour</button>;
}

export default function App() {
  return (
    <TourProvider steps={steps}>
      <StartButton />
      {/* ...your app... */}
    </TourProvider>
  );
}

2 · Theme with CSS variables (zero code)

Every visual decision of the default card is a --tour-* variable with a sensible fallback. Scope them under a class and pass it as classNames={{ root: "my-tour" }}, or inline via the theme prop:

.my-tour {
  --tour-bg: #16181d;          /* card background   */
  --tour-fg: #f9fafb;          /* card text         */
  --tour-accent: #4f46e5;      /* primary button    */
  --tour-radius: 14px;
  --tour-overlay-color: rgba(10, 12, 24, 0.68);
}

3 · Or bring your own components (fully headless)

Replace the card entirely with components={{ Card }}. You receive the whole tour state and controls as typed props — the library keeps handling positioning, the spotlight and animations. The gradient “Brand” flavor in the playground above is exactly this.

import type { TourCardProps } from "react-headless-tour";

function MyCard({ step, next, prev, stop, isLast, arrow }: TourCardProps) {
  return (
    <div className="my-design-system-popover">
      {arrow /* optional — skip it for an arrowless design */}
      <h3>{step.title}</h3>
      <p>{step.content}</p>
      <button onClick={next}>{isLast ? "Done" : "Next"}</button>
    </div>
  );
}

<TourProvider steps={steps} components={{ Card: MyCard }} />

API reference

Everything below is fully typed — your editor shows these same descriptions via IntelliSense.

<TourProvider> props

TourStep

useTour()

Call it anywhere under the provider — ideal for “restart tour” menu items or driving the tour from app logic. Custom Cards receive all of this as props too.

CSS variables

All accepted by the default card and overlay: --tour-bg, --tour-fg, --tour-muted, --tour-accent, --tour-accent-fg, --tour-radius, --tour-shadow, --tour-border, --tour-font, --tour-max-width, --tour-padding, --tour-arrow-size, --tour-overlay-color, --tour-z-index