`<bmx-tour>`

A guided walk through an application: each step dims the page around the thing it is about, and a card beside it says what that thing is for, with Back, Next and "2 of 5". Onboarding, a "what's new" after a release, help for a screen people find hard - written in the page, run in the browser, with nothing sent anywhere.

12 properties · 4 events · 5 methods · 14 parts

Example

New invoice

Export

INV-1042 · Acme Engineering · £1,240.00 · Due 14 Nov

Take the tour

The tour stores nothing: whether someone has seen it is the page's to remember, from bmxTourEnd.

A quick look round this screen - four steps, about a minute.

Every invoice starts here. Drafts are kept until you send them.

Try it now: click in the search box and the tour moves on by itself.

Open one to see its payments and history.

Export to CSV or Excel for your accountant.

Show markup

<div class="row" style="display: block">
  <div id="ex-tour-app" style="display: grid; gap: 12px; padding: 16px; border: 1px solid var(--bmx-border); border-radius: 12px; max-inline-size: 44rem">
    <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center">
      <bmx-button id="ex-tour-new">New invoice</bmx-button>
      <bmx-input id="ex-tour-search" label="Search invoices" hide-label placeholder="Search invoices" style="flex: 1 1 12rem"></bmx-input>
      <bmx-button id="ex-tour-export" variant="outline">Export</bmx-button>
    </div>
    <div id="ex-tour-list" style="padding: 12px; border-radius: 8px; background: var(--bmx-surface-sunken); color: var(--bmx-text-muted)">INV-1042 · Acme Engineering · £1,240.00 · Due 14 Nov</div>
  </div>
  <p style="margin: 12px 0 0"><bmx-button id="ex-tour-start" variant="soft">Take the tour</bmx-button></p>
</div>
<p class="note" id="ex-tour-out" role="status">The tour stores nothing: whether someone has seen it is the page's to remember, from <code>bmxTourEnd</code>.</p>

<bmx-tour id="ex-tour" label="Invoices tour">
  <bmx-tour-step heading="Welcome to invoices">A quick look round this screen - four steps, about a minute.</bmx-tour-step>
  <bmx-tour-step target="#ex-tour-new" heading="Raise an invoice" placement="bottom-start">Every invoice starts here. Drafts are kept until you send them.</bmx-tour-step>
  <bmx-tour-step target="#ex-tour-search" heading="Find anything" interactive advance-on="focusin">Try it now: click in the search box and the tour moves on by itself.</bmx-tour-step>
  <bmx-tour-step target="#ex-tour-list" heading="Your invoices" placement="top">Open one to see its payments and history.</bmx-tour-step>
  <bmx-tour-step target="#ex-tour-export" heading="Take it with you">Export to CSV or Excel for your accountant.</bmx-tour-step>
</bmx-tour>

<script type="module">
  await customElements.whenDefined('bmx-tour');
  const tour = document.getElementById('ex-tour');
  const out = document.getElementById('ex-tour-out');
  document.getElementById('ex-tour-start').addEventListener('click', () => tour.start());
  tour.addEventListener('bmxTourStepChanged', e => (out.textContent = `Step: ${e.detail.toValue}`));
  tour.addEventListener('bmxTourEnd', e => (out.textContent = e.detail.completed ? 'Tour finished.' : `Tour ended early (${e.detail.reason}) at "${e.detail.value}".`));
</script>

<bmx-tour id="tour" label="Welcome tour">
  <bmx-tour-step heading="Welcome">A quick look round - four steps.</bmx-tour-step>
  <bmx-tour-step target="#new-invoice" heading="Raise an invoice">Every invoice starts here.</bmx-tour-step>
  <bmx-tour-step target="#search" heading="Find anything" interactive advance-on="focus">Try it: click in the box.</bmx-tour-step>
  <bmx-tour-step heading="That's it">Open this tour again from Help.</bmx-tour-step>
</bmx-tour>
<script>tour.start();</script>

A step with a target scrolls it into view, cuts it out of the dimmed page and points the card at it, following it as the page scrolls or changes size. interactive lets the reader use the target there and then; advance-on moves on when they do (a click, a change). wait-for waits for a target that appears later; a target that never appears gets the card in the middle of the window, or (missing-target="skip") is passed over. next jumps to another step, and beforeChange and the cancellable bmxTourStepChange let the page decide where a tour goes.

Whether someone has seen a tour is the page's to remember (bmxTourEnd says how it ended); the tour stores nothing.

The card is a non-modal dialog named by its heading and described by its words, focused at every step; Tab stays in it while the page around it is blocked; the arrow keys move between steps; Escape ends the tour. Focus goes back where it was when the tour ends.

Properties

Property	Attribute	Type	Default	Description
`active`	`active`	`boolean`	`false`	Whether the tour is running. Setting it starts or ends the tour.
`backdrop`	`backdrop`	`boolean`	`true`	Dim the page around the target. `false` leaves the whole page in view and usable.
`beforeChange`	property only	`BmxTourGuard`	—	The page's own check before a step is left forward.
`closeOnBackdrop`	`close-on-backdrop`	`boolean`	`false`	A press on the dimmed page ends the tour.
`dismissible`	`dismissible`	`boolean`	`true`	The reader may leave the tour early: the close button, Skip and Escape.
`label`	`label`	`string`	—	The card's accessible name when a step has no heading.
`missingTarget`	`missing-target`	`'center' \| 'skip'`	`'center'`	A step whose target is not on the page: `center` shows its card in the middle of the window, `skip` passes over it.
`showProgress`	`show-progress`	`boolean`	`true`	Show "2 of 5" and the progress dots.
`spotlightPadding`	`spotlight-padding`	`number`	`8`	Space between the target and the edge of the cut-out, in pixels.
`spotlightRadius`	`spotlight-radius`	`number`	`8`	Corner radius of the cut-out, in pixels.
`strings`	`strings`	`Partial<BmxTourStrings> \| string`	—	Words to show instead of the English ones, as an object or JSON.
`value`	`value`	`string`	—	The current step, by value. Mutable: moving updates it.

Events

Event	Detail	Description
`bmxTourEnd`	`BmxTourEndDetail`	Fired when the tour ends, with how.
`bmxTourStart`	`{ value: string; index: number; }`	Fired when the tour starts.
`bmxTourStepChange`	`BmxTourStepChangeDetail`	Fired before the current step changes. Cancel it to stay.
`bmxTourStepChanged`	`BmxTourStepChangeDetail`	Fired after the current step has changed and its card is showing.

Methods

Method	Signature	Description
`goTo`	`goTo(step: string \| number) => Promise<boolean>`	Moves to a step by value or position. Resolves whether it moved.
`next`	`next() => Promise<boolean>`	Moves to the next step, after the page's checks; ends the tour from the last. Resolves whether it moved.
`previous`	`previous() => Promise<boolean>`	Moves to the step before. Resolves whether it moved.
`start`	`start(at?: string \| number) => Promise<boolean>`	Starts the tour, at the first step or at one given by value or position. Resolves whether it started.
`stop`	`stop() => Promise<void>`	Ends the tour.

Slots

Slot	Description
`(default)`	`bmx-tour-step` elements.

CSS shadow parts

Part	Description
`arrow`	The card's arrow, on the side facing the target.
`back`	The Back button.
`body`	The step's words.
`card`	The card.
`close`	The close button.
`dots`	The progress dots.
`footer`	The row of progress and buttons.
`heading`	The card's heading.
`layer`	The full-window layer holding the scrim and the card.
`next`	The Next (or Done) button.
`progress`	"2 of 5".
`scrim`	The dimmed page, with the cut-out.
`skip`	The "Skip tour" button.
`spotlight`	The ring around the cut-out.

CSS custom properties

Property	Description
`--bmx-tour-radius`	Corner radius of the card.
`--bmx-tour-ring`	The colour of the ring around the target.
`--bmx-tour-scrim`	The colour laid over the page around the target.
`--bmx-tour-width`	The card's width.