Tour

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.

Take the tour Search New

<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)