# Tour

> A card that walks people through an interface one step at a time, beside each element it explains.

## Anatomy

A `.tour` walks people through an interface one step at a time, beside each element it explains.

To build a tour:

1.  Make the card a `popover="manual"` dialog with one `<section>` per step.
2.  Set each section's `data-tour-target` to the id of the element it is about.
3.  Add a `.tour-progress` line, a `.tour-actions` row with Back, Next and Done buttons, and a close button.
4.  Add a button whose `data-tour-start` names the tour to start.

For one hint beside one control, use a [popover](/popover.html.md).

Take the tour Search New

## Search everything

Find files, people and settings from here.

## Create

Start a document, sheet or folder.

Back Next Done

```
<button type="button" data-tour-start="welcome">Take the tour</button>

<div id="welcome" class="tour" popover="manual" role="dialog">
  <section data-tour-target="search-button">
    <h2>Search everything</h2>
    <p>Find files, people and settings from here.</p>
  </section>
  <section data-tour-target="new-button">
    <h2>Create</h2>
    <p>Start a document, sheet or folder.</p>
  </section>
  <p class="tour-progress"></p>
  <div class="tour-actions">
    <button type="button" class="button text" data-tour-back>Back</button>
    <button type="button" class="button filled" data-tour-next>Next</button>
    <button type="button" class="button filled" data-tour-done>Done</button>
  </div>
  <button type="button" class="icon-button" data-tour-close aria-label="Close tour">
    <span class="material-symbols" aria-hidden="true">close</span>
  </button>
</div>
```

## Behavior

The `Tour` behavior shows one step at a time below its target. It flips the card above the target when there is no room below, rings the target and scrolls it into view. It skips steps whose target is missing or hidden. Back hides on the first step and Next on the last. Done shows only on the last step.

The step's heading names the card, and the card takes focus. Escape, Done or the close button ends the tour and returns focus to where it was. The card's `toggle` event tells the page, so it can, for example, remember that the user saw the tour.

From script, call `Expressive.Tour.start(el, index)`, `go(el, index)` and `end(el, completed)`. The tour fires `expressive:open`, and `expressive:change` with `{ step, index }`. It also fires `expressive:close` with `{ completed }`, which is true when Done ended the tour. `Expressive.Tour.i18n.progress` holds the `Step {current} of {total}` text. The root bundle starts the behavior on load. With the modular entry, call `Tour.Init()`.

## Tokens

| Token | Default |
| --- | --- |
| `--md-comp-tour-container-color` | `--md-sys-color-surface-container-high` |
| `--md-comp-tour-shape` | 16px |
| `--md-comp-tour-max-width` | 360px |
| `--md-comp-tour-gap` | 12px (from the target) |