Tour

A guided product tour that spotlights parts of the page step by step, with keyboard control and a focus trap.

Overlaystouronboardingwalkthrough

Workbench

Rendering Tour…

Installation

Copy the source into your project with the CLI. It lands under @/components/ui and is yours to edit.

npx mlola-ui add tour

Usage

TSX

"use client";

import * as React from "react";
import { Button } from "@/components/ui/button";
import { Tour } from "@/components/ui/tour";

export default function Example() {
  const [open, setOpen] = React.useState(false);
  return (
    <>
      <div className="ml-cluster">
        <Button id="tour-search" variant="secondary">Search</Button>
        <Button id="tour-new">New project</Button>
        <Button variant="subtle" onClick={() => setOpen(true)}>Take the tour</Button>
      </div>
      <Tour
        open={open}
        onOpenChange={setOpen}
        steps={[
          { target: "#tour-search", title: "Find anything", body: "Search projects, people and settings." },
          { target: "#tour-new", title: "Start here", body: "A project holds pages, members and billing." },
        ]}
      />
    </>
  );
}

Styling comes from the engine stylesheet and the nearest theme. Set it once at the root:

HTML

<html data-theme="graphite" data-mode="light">

HTML

The markup the example above renders, at rest. The interaction lives in the React component; from another framework, set the attributes below as the state changes.

HTML

<div class="ml-cluster">
  <button class="ml-button" type="button" data-variant="secondary" data-size="md" id="tour-search"><span class="ml-button-label">Search</span></button>
  <button class="ml-button" type="button" data-variant="primary" data-size="md" id="tour-new"><span class="ml-button-label">New project</span></button>
  <button class="ml-button" type="button" data-variant="subtle" data-size="md"><span class="ml-button-label">Take the tour</span></button>
</div>

Classes and attributes

A class names each element; data-* and aria-* attributes carry its variant and state. The values listed are the ones the stylesheet draws; the default needs no attribute.

Class	Attributes
`ml-tour`	—
`ml-tour-scrim`	`data-spotlight`
`ml-tour-spotlight`	—
`ml-tour-card`	`data-centered`
`ml-tour-head`	—
`ml-tour-count`	—
`ml-tour-skip`	—
`ml-tour-title`	—
`ml-tour-body`	—
`ml-tour-foot`	—
`ml-tour-dots`	—
`ml-tour-dot`	`data-active`
`ml-tour-button`	`data-primary`

Accessibility and theming

Semantic elements, accessible names and state relationships are part of the contract.
Keyboard, pointer and touch paths are operable; focus stays visible in every theme.
Light and dark modes pass WCAG AA contrast in all 5 canonical themes.
Reduced motion and forced colors keep meaning and operation.

Dependencies

Installed alongside this component. No third-party UI runtime is ever added.

@mlola-ui/behavior
@mlola-ui/icons

Open the standalone preview