Product Tour React component
A guided product tour: a spotlight glides from element to element over a dimmed page while a card beside it explains each one, with progress dots, Back, Next and Skip, arrow keys, and automatic placement on the side that has room.
When to use the Product Tour component
Use Product Tour to walk new users through a dashboard or app the first time they arrive, or to point out a new feature after a release. Each step dims everything except the thing being explained.
Keep tours short (three to five steps) and let people skip. Use onFinish to remember that someone completed it so it doesn't come back.
Installation
Add the Product Tour component to your project with the shadcn CLI. It lands in components/product-tour.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add https://reactframe.com/r/product-tour.jsonOr copy the source by hand and install its dependencies:
npm install motion clsx tailwind-mergeProps
<ProductTour /> accepts 13 props, all optional.
| Prop | Type | Default |
|---|---|---|
| steps | { target?: string; title: string; body?: React.ReactNode; placement?: TourPlacement }[] | DEFAULT_STEPS |
| open | boolean | — |
| defaultOpen | boolean | false |
| onOpenChange | (open: boolean) => void | — |
| onStepChange | (index: number) => void | — |
| onFinish Called when the last step's Done button is pressed (not when skipped). | () => void | — |
| triggerLabel A button that starts the tour. Leave out and control it with open / onOpenChange. | string | — |
| padding Space between the highlight and its element, in px. | number | 6 |
| closeOnOverlayClick Close when the dimmed area is clicked. | boolean | false |
| showProgress | boolean | true |
| contained Look for targets inside, and draw over, the nearest positioned ancestor instead of the page. | boolean | false |
| theme | "dark" | "light" | "dark" |
- steps{ target?: string; title: string; body?: React.ReactNode; placement?: TourPlacement }[]Default: DEFAULT_STEPS
- openboolean
- defaultOpenbooleanDefault: false
- onOpenChange(open: boolean) => void
- onStepChange(index: number) => void
- onFinish
Called when the last step's Done button is pressed (not when skipped).
() => void - triggerLabel
A button that starts the tour. Leave out and control it with open / onOpenChange.
string - padding
Space between the highlight and its element, in px.
numberDefault: 6 - closeOnOverlayClick
Close when the dimmed area is clicked.
booleanDefault: false - showProgressbooleanDefault: true
- contained
Look for targets inside, and draw over, the nearest positioned ancestor instead of the page.
booleanDefault: false - theme"dark" | "light"Default: "dark"
Show all 13 propsShow fewer
| className | string | — |
- classNamestring
FAQ
- How do I point a step at an element?
- Give the element something selectable, like data-tour="search", and set that step's target to '[data-tour="search"]'. Leave target out for a centred welcome or goodbye step.
- Where does the card go?
- On the side you ask for with placement if there's room, otherwise below, above, right or left, whichever fits first. It's always kept inside the screen (or the container).
- Can it run inside a card or preview?
- Yes. Set contained and place the tour inside a positioned container; it then only looks for targets in that container and dims just that area.
