Playground

Tour

A guided walkthrough: a spotlight on one element at a time with a card and Next, Back and Skip.

  • Built on native elements
  • The step card is a dialog named by its title and described by its text; it takes focus on every step.
  • Tab stays inside the card; Escape ends the tour and focus returns to where it was.
  • ArrowRight and ArrowLeft move between steps when the card has focus (mirrored in right-to-left).
  • Styles in one file: 02-buttons.css

Import

import '@monoline/css';
import {Tour} from '@monoline/react';

Not installed yet? Pick a route.

Copies the source and its styles into your project.

npx monoline add tour

Usage

import {useState} from 'react';
import {Tour} from '@monoline/react';

function Basic() {
  const [open, setOpen] = useState(false);
  return (
    <div>
      <div style={{display: 'flex', gap: 'var(--s4)', alignItems: 'center'}}>
        <button type="button" className="btn btn-solid" onClick={() => setOpen(true)}>Start tour</button>
        <button type="button" className="btn" id="tour-demo-a">Create</button>
        <button type="button" className="btn" id="tour-demo-b">Share</button>
      </div>
      <Tour
        open={open}
        onOpenChange={setOpen}
        steps={[
          {target: '#tour-demo-a', title: 'Create', content: 'Start a new project from here.'},
          {target: '#tour-demo-b', title: 'Share', content: 'Invite people by email.', placement: 'end'},
          {title: 'That is all', content: 'You can restart the tour at any time.'},
        ]}
      />
    </div>
  );
}

<Basic />

Examples

Three steps

The last step has no target, so its card is centred.

Props

TourProps

PropTypeDefaultDescription
steps requiredTourStep[]–The steps, in order.
openboolean–Whether the tour is showing, when controlled. Pair with `onOpenChange`.
defaultOpenbooleanfalseWhether the tour starts open when uncontrolled. Default false.
onOpenChange((open: boolean) => void)–Called with false when the tour ends: Skip, Escape or Done.
stepnumber–The current step index when controlled. Pair with `onStepChange`.
defaultStepnumber0The step to start on when uncontrolled. Default 0.
onStepChange((step: number) => void)–Called with the new index when the user moves between steps.
onFinish(() => void)–Called when the user finishes the last step (not when they skip or press Escape).
spotlightPaddingnumber6Extra space in px around the highlighted element. Default 6.
labelsTourLabels–Replaces the button text.

Data Attributes

State is exposed through attributes. Style it with these selectors, not with class toggles.

This component sets no state attributes.

CSS classes

ClassStylesheet
.btn02-buttons.css
.btn-block02-buttons.css
.btn-danger02-buttons.css
.btn-ghost02-buttons.css
.btn-lg02-buttons.css
.btn-line02-buttons.css
.btn-sm02-buttons.css
.btn-solid02-buttons.css
.tourtour.css
.tour-actionstour.css
.tour-cardtour.css
.tour-contenttour.css
.tour-counttour.css
.tour-overlaytour.css
.tour-spacertour.css
.tour-spotlighttour.css
.tour-titletour.css

Customization

Style it with the kit's tokens in your own CSS, loaded after @monoline/css. Prefer the attributes above over extra classes. See Theming for every token.

app.css
.btn {
  border-color: var(--accent);
}

Accessibility

  • The step card is a dialog named by its title and described by its text; it takes focus on every step.
  • Tab stays inside the card; Escape ends the tour and focus returns to where it was.
  • ArrowRight and ArrowLeft move between steps when the card has focus (mirrored in right-to-left).
  • Each step is announced politely as "Step n of m"; the highlighted element scrolls into view.
  • The overlay and spotlight are hidden from assistive technology; animation stops under prefers-reduced-motion.

Keyboard

KeysAction
TabStays inside the card
EscapeEnds the tour and focus returns to where it was
ArrowRight / ArrowLeftMove between steps when the card has focus (mirrored in right-to-left)