# Tour line

> 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.

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.

## Install

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

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

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): `text-morph`
- Docs and live preview: https://hairlineui.com/ui/tour-line
- Registry item (source): https://hairlineui.com/r/tour-line.json

## 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" },
  ]}
/>
```

## Once, after sign-up

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

```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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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` | `string` | `"var(--primary)"` | The frame’s colour: any CSS colour. |
| `doneLabel` | `string` | `"Done"` | The last step’s button. |

## 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.

## What it handles

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.

- **Your eye is carried**: One frame glides and reshapes itself onto each next element, so you never hunt.
- **The page stays usable**: Nothing blocks clicks; people can try what they’re shown.
- **Finds its targets**: Selectors or elements; off-screen ones scroll in first.
- **Follows the layout**: The frame and card track their target on scroll and resize.
- **Plain steps in**: An array of target, title and body; controlled or not.
- **Keyboard and screen readers**: The card is a labelled dialog that takes focus; Esc closes, arrows step.

## Replaces

a product tour library, a spotlight overlay, coach marks, an onboarding walkthrough, a feature tooltip

## Where it fits

- **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.

## Notes

- 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.

License: MIT (https://hairlineui.com/license#components)
