Appearance
Tour
A guided walk through a screen, one element at a time. Everything but the element dims, and a card beside it says what it is, with Back, Next and a count. Reach for it to introduce a screen the first time a person sees it, or to show a design's walkthrough as it would run.
tsx
/**
* A mail toolbar and a three-step tour of it, shown from the start.
* Next and Back walk it; a press on the dim does nothing; Escape or
* Done ends it, and the button starts it again.
*/
export function ToolbarTour(): UiChild {
const compose = tourTarget();
const archive = tourTarget();
const step = internalState<number | null>(0);
return (
<column width={percent(100)} height={percent(100)} padding={24} gap={24} backgroundColor="background">
<row gap={8} y="center">
<Button ref={compose.ref} label="Compose" variant="filled" />
<Button ref={archive.ref} label="Archive" variant="outlined" />
</row>
<Button label="Take the tour" variant="plain" onClick={() => (step.value = 0)} />
<Tour
step={step}
onStepChange={next => (step.value = next)}
steps={[
{ target: compose, title: 'Write a message', body: 'Start a new conversation from here.' },
{ target: archive, title: 'Clear it away', body: 'Archived mail leaves the inbox but is never deleted.' },
{ title: 'That is the toolbar', body: 'Take the tour again from the button below it.' }
]}
/>
</column>
);
}Naming what a step points at
A step points at a tourTarget(), given to the element as its ref. It is a cell rather than the element itself because a component runs before the refs of what it draws are called: the step learns where its element is once it is drawn, and a step whose element is not drawn yet waits for it rather than pointing at nothing.
| Step field | What it does |
|---|---|
target | The element it shows. Without one, the card is centred over a plain dim |
title | The card's heading, and its name for a screen reader |
body | A sentence or two under the title |
side | 'bottom' (default), 'top', 'start' or 'end': the side of the target the card is on |
Props
| Prop | Default | What it does |
|---|---|---|
steps | none | The steps, in order |
step | none | The step shown, from 0, for an application that owns it; null hides it |
defaultStep | 0 | The step it starts at, for a tour that owns its own |
onStepChange | none | Called with the step it asks for, and null when it ends |
padding | 8 | Room between the target and the edge of the lit hole, in pixels |
doneLabel | 'Done' | The last step's button |
Like every stateful control, it is controlled by step and onStepChange together, and owns its own step otherwise: a <Tour steps={…} /> with neither is shown from its first step and walks itself.
A screen showing its tour at a later step, beside the screen as written, wraps the screen in StartingInputs with of set to { Tour: { step: 1 } }.
The dim and the hole
The dim is the shadow of a rounded box laid over the target with placement: 'over', the overlay placement that lays an entry over its anchor at the anchor's size, grown by the offset. So the hole follows the target through scrolling and layout, as a tooltip follows its anchor. From one step to the next the hole glides, over the design's normal motion, from where it was to the new target; a step with no target shrinks it to a point in the middle of the last one, and the target after grows out of one. On a settled clock, a design tool's board, it is there at once. Around the hole, boxes reaching past the screen take every press and wheel, so the page under the dim stays as the tour left it; the target itself, in the hole, can still be pressed. The card has the keyboard while it is open: Escape ends the tour, and the arrow keys step through it.
Inside an OverlayScope
A tour drawn inside an OverlayScope dims that scope and nothing else, which is how a design tool plays a screen with a tour on it: the dim covers the played screen, scaled and clipped with it, and the tool around it stays usable. On a settled clock, a design tool's board, the dim and the card are drawn at rest.
What this page was checked against
Tour.spec.ts mounts a tour of three steps and asserts that the hole is the first target grown by the padding, with the card under it; that a press on the dim reaches nothing while one in the hole reaches the target; that Next glides the hole, the same dim, part way and then onto the next target, Back moves it back, a step with no target centres its card and shrinks the hole to a point in the middle of the last target, and Done ends the tour, reporting each step asked for; that Escape ends it; and that a null step shows nothing. A layout spec checks that placement: 'over' lays a node over its anchor, grown by the offset. The spec beside the example walks it to the end and starts it again.