All components (204)

Guided tour

Layers · Tour

What it is and when to use it

The welcome tour: one thing on the screen is highlighted, explained in a bubble, and then the next one is shown. The spotlight is measured again on scrolling and on window resize, so it does not keep pointing where the thing was a moment ago.

When to use it

The first time someone enters a screen with several pieces that do not explain themselves.
The target of each step is a CSS selector for what is pointed at; if it is out of view, the page scrolls to it. A step without a target, or whose target does not exist on the page, appears in the center instead of disappearing.
Controlled with index and onStepChange if the application keeps the step (to resume it, for example); if not, it keeps it itself and every time it opens it starts from the first one.

When not to

A one-sentence help on a button: Tooltip.
A process that has to be completed step by step (a sign-up, an order): Wizard.
A list of things to do to get the account ready: OnboardingList.

Keyboard: on opening, focus enters the bubble. Tab goes through Skip, Previous and Next and starts over without reaching anything on the page behind, which is inert; when advancing, focus stays on Next, so the whole tour is traversed with Enter. On the last step, Next becomes Finish, which notifies onFinish before closing. You can always leave: with Skip, with Escape or by pressing outside, and all of them notify onClose.

Accessibility: the bubble is a dialog with the step's title as its name and the content as its description, and shows where you are ("2 of 4"). Each new step is announced in a status region ("Step 2 of 4: Refine with the filters") without moving focus. On the first step, Previous is turned off.

Fine-tuning: no variables of its own. It is adjusted with the amset-tour__* classes (the veil, the spotlight and the bubble) and that of all floating layers, amset-floating.

What it looks like

Search the catalog

<Tour
  open={abierta}
  onClose={() => setAbierta(false)}
  steps={[
    { key: 'buscar', target: '#buscador', title: 'Find any piece', content: 'By name or by reference.' },
    { key: 'carrito', target: '#carrito', title: 'Your cart', content: 'With the total in view.' },
  ]}
/>

Props

Import it with import { Tour } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`onClose`required	`() => void`	Called on skipping, on closing with Escape and on finishing.
`open`required	`boolean`	—
`steps`required	`readonly TourStep[]`	—
`className`	`string`	Merged with the library classes; it does not replace them.
`finishText`	`string`	—
`index`	`number`	—
`nextText`	`string`	—
`onFinish`	`() => void`	Only when the end is reached, in addition to `onClose`.
`onStepChange`	`(index: number) => void`	—
`previousText`	`string`	—
`skipText`	`string`	—

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: