Skip to content
Browse documentation

A product tour drawn with one hairline frame: it draws itself round the first thing you’re shown, then glides and reshapes itself onto each next one, the card riding along.

Used forOnboardingNew featuresEmpty dashboardsAdmin and settings

Install with the shadcn CLI

$ npx shadcn@latest add https://hairlineui.com/r/tour-line.json

Registered the namespace? Then it’s shadcn add @hairline/tour-line. Set it up

Templates

Need the whole page?

61 Next.js landing pages, each designed from scratch. Try any of them live; one is $39, all of them $159, and 6 are free.

All 61 templates

Where it’s used

  • Onboarding

    A first-run tour of the main screen after sign-up.

  • New features

    Walking people through what changed in a release.

  • Empty dashboards

    Showing where the first project, import or invite starts.

  • Admin and settings

    A guided path through a dense settings page.

What it handles for you

Tour libraries jump a spotlight from box to box and pin a tooltip to it, so each step starts with hunting for where the highlight went.

Instead of wiring upa product tour librarya spotlight overlaycoach marksan onboarding walkthrougha feature tooltip
  1. Your eye is carried

    One frame glides and reshapes itself onto each next element, so you never hunt.

  2. The page stays usable

    Nothing blocks clicks; people can try what they’re shown.

  3. Finds its targets

    Selectors or elements; off-screen ones scroll in first.

  4. Follows the layout

    The frame and card track their target on scroll and resize.

  5. Plain steps in

    An array of target, title and body; controlled or not.

  6. Keyboard and screen readers

    The card is a labelled dialog that takes focus; Esc closes, arrows step.

Overview

Product tours usually jump a spotlight from one box to the next, so the eye has to find where it went. Tour line keeps one hairline frame in your colour and moves it. Opening, the frame draws itself round the first thing you’re shown while the rest of the page dims a little and the step card settles beside it. Next, the same frame glides and reshapes itself onto the next element on springs, its corners matching each target’s, the dimmed window moving with it and the card riding along to its new place, so your eye is carried the whole way and never hunts. Close and the frame unwinds to nothing. The page stays usable underneath, so people can try the thing they’re being shown. Targets are CSS selectors or elements; off-screen ones scroll into view first, and the frame follows them on scroll and resize.

States

open
The frame draws itself round the first target from its top-left corner (620ms) while the page dims in with it; the card fades in beside the target, below it when there’s room and above when not.
next
The frame’s position, size and corner radius move to the new target on springs a little under critical (settled in about 450ms, interruptible: Next mid-glide re-aims from where it is); the dimmed window is cut from the same frame every frame, and the card slides to its new place (620ms). The title morphs; the body fades in.
scroll in
A target out of view scrolls to the middle of the screen first (smoothly), then the frame moves.
close
The frame unwinds to nothing from its start while the dim fades (420ms), then the layer goes.
reduced motion
The frame and window appear in place at each step; the page scrolls without smoothing.

Usage

usage.tsx
import { TourLine } from "@/components/tour-line";<TourLine  open={open}  onOpenChange={setOpen}  steps={[    { target: "#search", title: "Find anything", body: "Press / from anywhere." },    { target: "#new-project", title: "Start a project" },  ]}/>

Depends on lucide-react, installed for you by the CLI along with the keyframes it needs.

Works with

Once, after sign-up

Open it the first time someone lands on the dashboard and remember that they finished.

example.tsx
"use client";import * as React from "react";import { TourLine } from "@/components/tour-line";export function FirstRunTour({ seen }: { seen: boolean }) {  const [open, setOpen] = React.useState(!seen);  return (    <TourLine      open={open}      onOpenChange={(next) => {        setOpen(next);        if (!next) fetch("/api/me/tour-seen", { method: "POST" });      }}      steps={[        { target: "[data-tour=search]", title: "Find anything", body: "Projects, people and settings." },        { target: "[data-tour=new]", title: "Start a project", body: "It copies your last setup." },        { target: "[data-tour=inbox]", title: "Your inbox", body: "Mentions and approvals land here." },      ]}    />  );}

Props

steps
TourStep[]
Each step: target (a CSS selector or a function returning the element), title, and optionally body.
open / defaultOpen / onOpenChange
boolean / boolean / (open) => void
Whether the tour is showing, controlled or not.
step / defaultStep / onStepChange
number / number / (step) => void
Which step shows, controlled or not.
color= "var(--primary)"
string
The frame’s colour: any CSS colour.
doneLabel= "Done"
string
The last step’s button.

Accessibility and motion

  • The card is role="dialog" with aria-modal="false", labelled by its title, and takes focus when the tour opens; Esc closes and ← → step. The page underneath stays usable.
  • The frame is one SVG path driven by five springs from ui-interaction-motion.ts (installed with it); nothing re-renders while it glides.
  • It renders in a portal over the page, so it works from anywhere in your tree.
  • Installs Text morph. With reduced motion the frame and window appear in place.

Requirements

React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

The CLI also installs Text morph.

Source

"use client";import * as React from "react";import { createPortal } from "react-dom";import { X } from "lucide-react";import { TextMorph } from "./text-morph";import { createSpring, type Spring } from "./ui-interaction-motion";/* ───────────────────────────────────────────────────────── * TOUR LINE: a product tour drawn with one hairline frame * *   open      the frame draws itself round the first thing you're *             shown, the rest of the page dims a little, and the *             step card settles beside it *   next      the same frame glides and reshapes itself onto the next *             element on springs, corners and all, the dimmed window *             cut from it every frame and the card riding along *   close     the frame unwinds to nothing and the page comes back * * Non-blocking: the page stays usable, so people can try the thing * they're being shown. Esc closes, ← → step. Targets are CSS * selectors or elements; the frame follows them on scroll and * resize. * ───────────────────────────────────────────────────────── */export interface TourStep {  /** A CSS selector, or a function returning the element. */  target: string | (() => Element | null);  title: string;  body?: React.ReactNode;}export interface TourLineProps {  steps: TourStep[];  open?: boolean;  defaultOpen?: boolean;  onOpenChange?: (open: boolean) => void;  step?: number;  defaultStep?: number;  onStepChange?: (step: number) => void;  /** The thread's colour: any CSS colour. Defaults to --primary. */  color?: string;  /** The last step's button. */  doneLabel?: string;}type Rect = { x: number; y: number; w: number; h: number; r: number };const EASE = "cubic-bezier(0.16,1,0.3,1)";const FOCUS = "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:ring-offset-2 focus-visible:ring-offset-popover";const PAD = 6;const CARD_W = 300;const GAP = 14;interface Engine {  rect: Rect | null;  frame: number;  moving: boolean;  springs: { x: Spring; y: Spring; w: Spring; h: Spring; r: Spring } | null;}/** The frame's five springs, made once; a little under critical so it settles with the smallest give. */function springsFor(e: Engine, paint: () => void) {  if (!e.springs) {    const make = () => createSpring(0, { stiffness: 190, damping: 24 }, paint, 0.05);    e.springs = { x: make(), y: make(), w: make(), h: make(), r: make() };  }  return e.springs;}const reducedQuery = "(prefers-reduced-motion: reduce)";const subscribeReduced = (onChange: () => void) => {  const query = window.matchMedia(reducedQuery);  query.addEventListener("change", onChange);  return () => query.removeEventListener("change", onChange);};const useReducedMotion = () =>  React.useSyncExternalStore(subscribeReduced, () => window.matchMedia(reducedQuery).matches, () => false);const subscribeNothing = () => () => {};const useMounted = () => React.useSyncExternalStore(subscribeNothing, () => true, () => false);const inOut = (t: number) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2);function resolve(target: TourStep["target"]) {  if (typeof target === "function") return target();  return document.querySelector(target);}function rectOf(el: Element | null): Rect | null {  if (!el) return null;  const b = el.getBoundingClientRect();  const radius = parseFloat(getComputedStyle(el).borderTopLeftRadius) || 0;  return { x: b.left - PAD, y: b.top - PAD, w: b.width + PAD * 2, h: b.height + PAD * 2, r: Math.min(radius + PAD, (b.height + PAD * 2) / 2, 24) };}/** A rounded rect as one closed path, from the top-left corner's end. */const outline = (r: Rect) => {  const k = Math.max(0, Math.min(r.r, r.w / 2, r.h / 2));  return `M ${r.x + k} ${r.y} H ${r.x + r.w - k} A ${k} ${k} 0 0 1 ${r.x + r.w} ${r.y + k} V ${r.y + r.h - k} A ${k} ${k} 0 0 1 ${r.x + r.w - k} ${r.y + r.h} H ${r.x + k} A ${k} ${k} 0 0 1 ${r.x} ${r.y + r.h - k} V ${r.y + k} A ${k} ${k} 0 0 1 ${r.x + k} ${r.y} Z`;};export function TourLine({  steps,  open: openProp,  defaultOpen = false,  onOpenChange,  step: stepProp,  defaultStep = 0,  onStepChange,  color = "var(--primary)",  doneLabel = "Done",}: TourLineProps) {  const reduced = useReducedMotion();  const mounted = useMounted();  const [ownOpen, setOwnOpen] = React.useState(defaultOpen);  const [ownStep, setOwnStep] = React.useState(defaultStep);  const open = openProp ?? ownOpen;  const index = Math.max(0, Math.min(steps.length - 1, stepProp ?? ownStep));  const step = steps[index];  const titleId = React.useId();  const [shown, setShown] = React.useState(false); // the layer stays while the thread unwinds on close  const [card, setCard] = React.useState<{ x: number; y: number; above: boolean } | null>(null);  const threadRef = React.useRef<SVGPathElement>(null);  const dimRef = React.useRef<SVGPathElement>(null);  const svgRef = React.useRef<SVGSVGElement>(null);  const cardRef = React.useRef<HTMLDivElement>(null);  const now = React.useRef<Engine>({ rect: null, frame: 0, moving: false, springs: null });  const setOpen = (next: boolean) => {    if (openProp === undefined) setOwnOpen(next);    onOpenChange?.(next);  };  const goTo = (next: number) => {    if (next < 0 || next >= steps.length) return;    if (stepProp === undefined) setOwnStep(next);    onStepChange?.(next);  };  const place = React.useCallback((r: Rect) => {    const vw = window.innerWidth;    const vh = window.innerHeight;    const width = Math.min(CARD_W, vw - 24);    const height = cardRef.current?.offsetHeight ?? 150;    const above = r.y + r.h + GAP + height > vh - 12 && r.y - GAP - height > 12;    const x = Math.max(12, Math.min(r.x, vw - width - 12));    const y = above ? r.y - GAP - height : Math.min(r.y + r.h + GAP, vh - height - 12);    setCard((c) => (c && c.x === x && c.y === y && c.above === above ? c : { x, y, above }));  }, []);  // Draw the thread at rest round one rect, and the dimmed window.  const rest = React.useCallback((r: Rect) => {    const thread = threadRef.current;    const dim = dimRef.current;    const svg = svgRef.current;    if (svg) svg.setAttribute("viewBox", `0 0 ${window.innerWidth} ${window.innerHeight}`);    if (thread) {      thread.setAttribute("d", outline(r));      thread.style.strokeDasharray = "none";    }    if (dim) dim.setAttribute("d", `M 0 0 H ${window.innerWidth} V ${window.innerHeight} H 0 Z ${outline(r)}`);  }, []);  // One frame of the glide: the frame and the dimmed window at the springs' rect; at rest it hands back to `rest`.  const paintFrame = React.useCallback(() => {    const e = now.current;    const sp = e.springs;    if (!sp) return;    const r = { x: sp.x.get(), y: sp.y.get(), w: Math.max(4, sp.w.get()), h: Math.max(4, sp.h.get()), r: Math.max(0, sp.r.get()) };    const thread = threadRef.current;    const dim = dimRef.current;    if (thread) {      thread.setAttribute("d", outline(r));      thread.style.strokeDasharray = "none";    }    if (dim) {      dim.setAttribute("d", `M 0 0 H ${window.innerWidth} V ${window.innerHeight} H 0 Z ${outline(r)}`);      dim.style.opacity = "1";    }    const still = [sp.x, sp.y, sp.w, sp.h, sp.r].every((s) => s.getVelocity() === 0 && s.get() === s.getTarget());    if (still && e.moving && e.rect) {      e.moving = false;      rest(e.rect);    }  }, [rest]);  // Open, step and close: one animation each, written straight to the SVG.  React.useEffect(() => {    if (!open) return;    const e = now.current;    const el = step ? resolve(step.target) : null;    if (!el) return;    let cancelled = false;    const run = () => {      if (cancelled) return;      const to = rectOf(el);      if (!to) return;      const from = e.rect;      setShown(true);      place(to);      cancelAnimationFrame(e.frame);      const thread = threadRef.current;      const dim = dimRef.current;      if (!thread || !dim || reduced) {        e.rect = to;        rest(to);        return;      }      svgRef.current?.setAttribute("viewBox", `0 0 ${window.innerWidth} ${window.innerHeight}`);      if (from) {        // Next: the same frame glides and reshapes itself onto the new target on springs, the dimmed window with it.        const sp = springsFor(e, paintFrame);        e.moving = true;        sp.x.set(to.x);        sp.y.set(to.y);        sp.w.set(to.w);        sp.h.set(to.h);        sp.r.set(to.r);        e.rect = to;        return;      }      // Open: the frame draws itself round the first target while the page dims.      const sp = springsFor(e, paintFrame);      [sp.x, sp.y, sp.w, sp.h, sp.r].forEach((s, i) => s.jump([to.x, to.y, to.w, to.h, to.r][i]));      thread.setAttribute("d", outline(to));      const total = thread.getTotalLength();      // Set the dash before the first frame paints, or the whole outline flashes for a frame.      thread.style.strokeDasharray = `0.01 ${total + 20}`;      dim.style.opacity = "0";      e.moving = true;      const start = performance.now();      const tick = (t: number) => {        const k = inOut(Math.min(1, (t - start) / 620));        thread.style.strokeDasharray = `${Math.max(0.01, total * k)} ${total + 20}`;        dim.style.opacity = String(k);        if (k < 1) e.frame = requestAnimationFrame(tick);        else {          e.moving = false;          e.rect = to;          rest(to);        }      };      e.frame = requestAnimationFrame(tick);    };    // Bring the target into view first, then draw.    const b = el.getBoundingClientRect();    const inView = b.top >= 0 && b.bottom <= window.innerHeight && b.left >= 0 && b.right <= window.innerWidth;    if (inView) run();    else {      el.scrollIntoView({ block: "center", inline: "nearest", behavior: reduced ? "auto" : "smooth" });      const timer = window.setTimeout(run, reduced ? 0 : 420);      return () => {        cancelled = true;        window.clearTimeout(timer);      };    }    return () => {      cancelled = true;    };  }, [open, step, reduced, place, rest, paintFrame]);  // Close: the thread unwinds to nothing, then the layer goes.  React.useEffect(() => {    if (open || !shown) return;    const e = now.current;    const thread = threadRef.current;    const dim = dimRef.current;    cancelAnimationFrame(e.frame);    if (e.springs) Object.values(e.springs).forEach((sp) => sp.stop());    e.moving = false;    if (!thread || !dim || reduced || !e.rect) {      e.rect = null;      const t = window.setTimeout(() => setShown(false), 0);      return () => window.clearTimeout(t);    }    const total = thread.getTotalLength();    const start = performance.now();    const tick = (t: number) => {      const k = inOut(Math.min(1, (t - start) / 420));      thread.style.strokeDasharray = `0 ${total * k} ${Math.max(0.01, total * (1 - k))} ${total + 20}`;      dim.style.opacity = String(1 - k);      if (k < 1) e.frame = requestAnimationFrame(tick);      else {        e.rect = null;        setShown(false);      }    };    e.frame = requestAnimationFrame(tick);    return () => cancelAnimationFrame(e.frame);  }, [open, shown, reduced]);  // Follow the target on scroll and resize.  React.useEffect(() => {    if (!open) return;    const follow = () => {      const e = now.current;      if (e.moving || !step) return;      const r = rectOf(resolve(step.target));      if (!r) return;      e.rect = r;      rest(r);      place(r);    };    window.addEventListener("scroll", follow, { passive: true, capture: true });    window.addEventListener("resize", follow);    return () => {      window.removeEventListener("scroll", follow, { capture: true });      window.removeEventListener("resize", follow);    };  }, [open, step, rest, place]);  // Keyboard: Esc closes, arrows step. Focus goes to the card when the tour opens.  React.useEffect(() => {    if (!open) return;    const key = (e: KeyboardEvent) => {      if (e.key === "Escape") setOpen(false);      else if (e.key === "ArrowRight") goTo(index + 1);      else if (e.key === "ArrowLeft") goTo(index - 1);    };    window.addEventListener("keydown", key);    return () => window.removeEventListener("keydown", key);  });  // Focus moves to the card once, when the tour opens and the card has its place.  const focusPending = React.useRef(false);  React.useEffect(() => {    if (open) focusPending.current = true;  }, [open]);  React.useEffect(() => {    if (!open || !card || !focusPending.current) return;    focusPending.current = false;    cardRef.current?.focus({ preventScroll: true });  }, [open, card]);  React.useEffect(() => {    const e = now.current;    return () => {      cancelAnimationFrame(e.frame);      if (e.springs) Object.values(e.springs).forEach((sp) => sp.stop());      e.springs = null;    };  }, []);  if (!mounted || (!open && !shown)) return null;  const last = index === steps.length - 1;  const dimFill = `color-mix(in oklab, black ${26}%, transparent)`;  return createPortal(    <div className="pointer-events-none fixed inset-0 z-[90]">      <svg ref={svgRef} aria-hidden="true" className="absolute inset-0 size-full overflow-visible">        <path ref={dimRef} fillRule="evenodd" style={{ fill: dimFill, opacity: 0 }} />        <path ref={threadRef} fill="none" stroke={color} strokeWidth={1.75} strokeLinecap="round" strokeLinejoin="round" />      </svg>      {step && (        <div          ref={cardRef}          role="dialog"          aria-modal="false"          aria-labelledby={titleId}          tabIndex={-1}          className="pointer-events-auto absolute left-0 top-0 rounded-[16px] bg-popover p-4 text-popover-foreground shadow-[0_0_0_1px_var(--border)] outline-none"          style={{            width: `min(${CARD_W}px, calc(100vw - 24px))`,            transform: card ? `translate3d(${card.x}px, ${card.y}px, 0)` : "translate3d(-9999px,0,0)",            opacity: open && card ? 1 : 0,            transition: reduced ? "none" : `transform 620ms ${EASE}, opacity 260ms ${EASE}`,          }}        >          <div className="flex items-start justify-between gap-3">            <p className="text-[11.5px] font-medium tabular-nums" style={{ color }}>              <TextMorph>{`Step ${index + 1} of ${steps.length}`}</TextMorph>            </p>            <button              type="button"              aria-label="Close tour"              onClick={() => setOpen(false)}              className={`-m-1 flex size-6 cursor-pointer items-center justify-center rounded-full text-muted-foreground transition-colors hover:text-foreground ${FOCUS}`}            >              <X className="size-3.5" />            </button>          </div>          <h2 id={titleId} className="mt-1 text-[15px] font-medium tracking-[-0.01em] text-foreground">            <TextMorph>{step.title}</TextMorph>          </h2>          {step.body && (            <div key={index} className="mt-1 text-[13px] leading-[1.5] text-muted-foreground motion-safe:animate-[ui-fade-in_320ms_ease-out_80ms_backwards]">              {step.body}            </div>          )}          <div className="mt-3.5 flex items-center justify-between gap-2">            <div className="flex gap-1" aria-hidden="true">              {steps.map((_, i) => (                <span                  key={i}                  className="h-1 rounded-full transition-[width,background-color] duration-500"                  style={{ width: i === index ? 14 : 4, background: i <= index ? color : "color-mix(in oklab, var(--foreground) 16%, transparent)", transitionTimingFunction: EASE }}                />              ))}            </div>            <div className="flex gap-1.5">              {index > 0 && (                <button                  type="button"                  onClick={() => goTo(index - 1)}                  className={`h-8 cursor-pointer rounded-full px-3 text-[12.5px] text-muted-foreground transition-colors hover:text-foreground ${FOCUS}`}                >                  Back                </button>              )}              <button                type="button"                onClick={() => (last ? setOpen(false) : goTo(index + 1))}                className={`h-8 cursor-pointer rounded-full bg-primary px-3.5 text-[12.5px] font-medium text-primary-foreground transition-[scale] duration-200 active:scale-[0.97] ${FOCUS}`}              >                <TextMorph>{last ? doneLabel : "Next"}</TextMorph>              </button>            </div>          </div>        </div>      )}    </div>,    document.body,  );}

Registry item: /r/tour-line.json