Tour React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Tour is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import Tour from @/components/ui/tour.

import { useRef } from "react"
import { Button } from "@/components/ui/button"
import { Tour, type TourStep } from "@/components/ui/tour"

export function ClientsTour() {
  const search = useRef<HTMLInputElement>(null)
  const invoice = useRef<HTMLButtonElement>(null)
  const steps: TourStep[] = [
    { id: "welcome", title: "Welcome to Northwind CRM", content: "We show you where everything is in 30 seconds." },
    { id: "search", target: search, title: "Find any client", content: "A name, an EIN or a city." },
    { id: "invoice", target: invoice, title: "Issue an invoice", content: "Press New invoice.", advanceOn: "click" },
  ]
  return (
    <Tour
      steps={steps}
      persistKey="northwind-crm:tour"
      autoStart
      shortcut="shift+h"
      labels={{ next: "Continue" }}
    >
      <input ref={search} placeholder="Search clients" />
      <Button ref={invoice}>New invoice</Button>
    </Tour>
  )
}

Props

• steps*
  TourStep[]

  The steps: { id, target? (selector, function or ref), title, content?, media?, side? (top / right / bottom / left / auto), align?, spotlightPadding?, spotlightRadius?, interactive?, advanceOn?: "click", beforeEnter?, nextLabel? }. A step without a target, or whose target is not found within 1s, shows a centered card.

• defaultOpendefault false
  boolean

  Starts open. Use open / onOpenChange to control it, or start() from useTour / setApi.

• open
  boolean

  Controlled open state. Only one tour shows at a time; a second one waits for the first to close.

• onOpenChange
  (open: boolean) => void

  Called when the tour opens or closes.

• defaultStepdefault 0
  number

  The step index it starts at.

• step
  number

  Controlled step index.

• onStepChange
  (step: number) => void

  Called with the new index on Next, Back, a dot, a swipe or goTo.

• onComplete
  () => void

  Called when the last step's Done is pressed (or finish()).

• onSkip
  () => void

  Called on Skip, the close button, Escape, an overlay click with closeOnOverlayClick, or skip().

• persistKeydefault ""
  string

  Local storage key that remembers the tour was completed or skipped. autoStart does not start a finished tour; start() still does, and reset() forgets it.

• autoStartdefault false
  boolean

  Opens once after hydration and a 600ms settle, unless persistKey says it was already finished.

• shortcutdefault ""
  string

  A global key that starts the tour, in mod+k notation. Empty binds nothing; the demo passes "shift+h" (the showcase owns ?).

• spotlightdefault true
  boolean

  Dims the page with a rounded cutout around the target and blocks clicks elsewhere. false shows only the cards, with an arrow (a ring alone marks the target when the card is docked), and leaves the page usable (coachmarks).

• overlayOpacitydefault 0.55
  number

  Strength of the dim. Dark mode adds 0.1 so the page still recedes behind the card.

• spotlightPaddingdefault 8
  number

  Room in px between the target and the edge of the cutout. Steps can override it.

• spotlightRadiusdefault 14
  number

  Corner radius of the cutout in px, capped at half the smaller side. Steps can override it.

• showProgressdefault "dots"
  "dots" | "fraction" | "bar" | "none"

  How the card shows where you are: dots (clickable), 2 / 5, a thin bar, or nothing (screen readers still hear it).

• sizedefault "md"
  "sm" | "md"

  Card width 288 / 340px (never wider than the screen minus 24px), with matching padding and type.

• radiusdefault "lg"
  "none" | "sm" | "md" | "lg" | "full"

  Card corners: 0, 12, 16 or 24px; full falls back to lg. The docked phone card keeps its 28px sheet top.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Color of the Next button and the progress.

• colordefault ""
  string

  Any CSS color for the Next button and the progress; replaces the tone.

• showSkipdefault true
  boolean

  A Skip button in the card on every step but the last.

• showClosedefault true
  boolean

  The × in the card's corner (on phones it shows only when Skip is hidden). It skips the tour.

• keyHintsdefault true
  boolean

  Shows the → key on the Next button on desktops. Hidden on touch screens.

• closeOnOverlayClickdefault false
  boolean

  A click on the dimmed area skips the tour. Off by default so a stray tap does not end it.

• scrollBehaviordefault "smooth"
  "smooth" | "instant"

  How targets scroll into view (instant under reduced motion). Nested scrollers scroll too.

• mobileLayoutdefault "docked"
  "docked" | "popover"

  Below 768px the card docks at the bottom where the thumb is, with a 44px Next and swipe paging, and targets scroll into the top half. popover keeps the desktop card.

• dockeddefault false
  boolean

  Docks the card at every width, e.g. inside a phone mockup.

• container
  Element | null

  Where the overlay renders (default document.body). A transformed element becomes the frame: the dim, the spotlight and the docked card stay inside it.

• setApi
  (api: TourApi) => void

  Receives { start(stepId?), next(), previous(), goTo(index | id), skip(), finish(), reset() } once mounted.

• labels
  Partial<TourLabels>

  Every string: next "Next", back "Back", skip "Skip tour", done "Done", close "Close tour", progress(i, n) "Step i of n", stepAnnounce(i, n, title), skipped "Tour closed", completed "Tour completed". DEFAULT_TOUR_LABELS has the English set.

• classNames
  Partial<Record<"overlay" | "spotlight" | "card" | "media" | "title" | "content" | "progress" | "actions" | "close" | "handle", string>>

  Extra classes for the inner parts.

• children
  ReactNode

  Rendered in place; anything inside can read the tour with useTour().

Parts

FAQ

More React overlay components