Tour

A guided walk through a page. Each step highlights an element and explains it in a card next to it, with buttons to go forward and back. Use it the first time someone opens a page with parts that are not obvious.

General

Each step has a title, a content and a target, a CSS selector of the element to highlight. open and onClose are yours to keep.

Controlled and without a target

current and onCurrentChange keep the step in your state, and onFinish runs when the last one is done, for example to remember that the tour was seen. A step without a target, like a welcome, is centered.

APIs

Tour.Props

Attribute	Description	Type	Accepted values	Default
steps	the steps of the tour	TourStep`[]`	-	-
open	shows the tour	`boolean`	-	-
onClose	called on Skip, on Escape and when the last step is done	`() => void`	-	-
current	the step in view, to control it	`number`	-	-
initialCurrent	the step on the first render	`number`	-	`0`
onCurrentChange	called with the new step	`(index: number) => void`	-	-
onFinish	called when the last step is done, before `onClose`	`() => void`	-	-
previousLabel	name of the button to go back	`string`	-	`Back`
nextLabel	name of the button to go forward	`string`	-	`Next`
finishLabel	name of the button of the last step	`string`	-	`Done`
skipLabel	name of the button that closes the tour	`string`	-	`Skip`
stepLabel	text with the position of the step	`(index: number, count: number) => string`	-	`1 of 3`
spotlightPadding	space between the target and the highlight, in px	`number`	-	`6`
...	native props, passed to the root `div`	`HTMLAttributes`	`'id', ...`	-

TourStep

Attribute	Description	Type	Accepted values	Default
title	name of the step	`ReactNode`	-	-
content	the explanation	`ReactNode`	-	-
target	what the step points at: a CSS selector, an element, or a function that returns one	`string` / `HTMLElement` / `() => HTMLElement`	-	-

Behavior

• Highlight: the page is dimmed, and the target is left clear, with a little space around it. It follows the target when the page scrolls or the window is resized.
• Scrolling: the target is scrolled into view when its step comes.
• Card: it opens under the target, and above it when there is not room below. It stays inside the screen.
• No target: without a target, or when it is not found, the card is centered and nothing is highlighted.
• Closing: Skip and Escape call onClose, and so does the last step, after onFinish. The focus goes back to where it was.

Ref

The ref points at the root div, which covers the screen.

Accessibility

The card is a modal dialog, named by the title and described by the content, and it takes the focus on every step. Tab and Shift Tab cycle through its buttons, and Escape closes it. The position of the step is also a text, like "2 of 3". The page behind is dimmed but not hidden, so keep the text of the step complete enough to stand on its own.

Edit this page on GitHub