Tour

A guided tour that helps users understand the interface.

Anatomy

const tour = useTour({ steps: [...] })

<Tour.Root tour={tour}>
  <Tour.Backdrop />
  <Tour.Spotlight />
  <Tour.Positioner>
    <Tour.Content>
      <Tour.Arrow>
        <Tour.ArrowTip />
      </Tour.Arrow>
      <Tour.Title />
      <Tour.Description />
      <Tour.ProgressText />
      <Tour.CloseTrigger />
      <Tour.Actions>
        <Tour.ActionTrigger />
      </Tour.Actions>
    </Tour.Content>
  </Tour.Positioner>
</Tour.Root>

Examples

Step Types

Demonstrate all three step types in a single tour: dialog for welcome/completion, tooltip anchored to elements, and floating for fixed-position content.

Progress

Display a visual progress indicator at the bottom of the tour content showing how far along the user is.

Skip

Allow users to skip the entire tour at any step by adding a skip action.

Keyboard Navigation

Enable arrow key navigation between tour steps using the keyboardNavigation prop.

Events

Listen to tour lifecycle events like onStepChange and onStatusChange to track user progress.

Wait for Click

Use the effect function with waitForEvent to wait for user interaction before proceeding to the next step.

Wait for Input

Create form tutorials that wait for users to enter valid input before advancing.

Wait for Element

Wait for dynamically rendered elements to appear in the DOM before showing a step.

Async

Load data asynchronously and update step content before displaying it using the effect function with show() and update().

Guides

Step Types

The tour machine supports different types of steps, allowing you to create a diverse and interactive tour experience. The available step types are defined in the StepType type:

• tooltip: Displays the step content as a tooltip, typically positioned near the target element.

• dialog: Shows the step content in a modal dialog centered on screen, useful for starting or ending the tour. This usually don't have a target defined.

• floating: Presents the step content as a floating element, which can be positioned flexibly on the screen. This usually don't have a target defined.

• wait: A special type that waits for a specific condition before proceeding to the next step.

const steps: TourStepDetails[] = [
  {
    id: 'step-1',
    type: 'tooltip',
    placement: 'top-start',
    target: () => document.querySelector('#target-1'),
    title: 'Tooltip Step',
    description: 'This is a tooltip step',
  },
  {
    id: 'step-2',
    type: 'dialog',
    title: 'Dialog Step',
    description: 'This is a dialog step',
  },
  {
    id: 'step-3',
    type: 'floating',
    placement: 'top-start',
    title: 'Floating Step',
    description: 'This is a floating step',
  },
  {
    id: 'step-4',
    type: 'wait',
    title: 'Wait Step',
    description: 'This is a wait step',
    effect({ next }) {
      // do something and go next
      // you can also return a cleanup
    },
  },
]

Actions

Every step supports a list of actions that are rendered in the step footer.Use the actions property to define each action.

const steps: TourStepDetails[] = [
  {
    id: 'step-1',
    type: 'dialog',
    title: 'Dialog Step',
    description: 'This is a dialog step',
    actions: [{ label: 'Show me a tour!', action: 'next' }],
  },
]

Tooltip Placement

Use the placement property to define the placement of the tooltip.

const steps: TourStepDetails[] = [
  {
    id: 'step-1',
    type: 'tooltip',
    placement: 'top-start',
    // ...
  },
]

Hide Arrow

Set arrow: false in the step property to hide the tooltip arrow. This is only useful for tooltip steps.

const steps: TourStepDetails[] = [
  {
    id: 'step-1',
    type: 'tooltip',
    arrow: false,
  },
]

Hide Backdrop

Set backdrop: false in the step property to hide the backdrop. This applies to all step types except the wait step.

const steps: TourStepDetails[] = [
  {
    id: 'step-1',
    type: 'dialog',
    backdrop: false,
  },
]

Effects

Step effects are functions that are called before a step is opened. They are useful for adding custom logic to a step.

This function provides the following methods:

• next(): Call this method to move to the next step.
• show(): Call this method to show the current step.
• update(details: StepDetails): Call this method to update the details of the current step (say, after data has been fetched).

const steps: TourStepDetails[] = [
  {
    id: 'step-1',
    type: 'tooltip',
    effect({ next, show, update }) {
      fetchData().then((res) => {
        // update the step details
        update({ title: res.title })
        // then show show the step
        show()
      })

      return () => {
        // cleanup fetch data
      }
    },
  },
]

Wait

Wait steps are useful when you need to wait for a specific condition before proceeding to the next step.

Use the step effect function to perform an action and then call next() to move to the next step.

Note: You cannot call show() in a wait step.

const steps: TourStepDetails[] = [
  {
    id: 'step-1',
    type: 'wait',
    effect({ next }) {
      const button = document.querySelector('#button')
      const listener = () => next()
      button.addEventListener('click', listener)
      return () => button.removeEventListener('click', listener)
    },
  },
]

Styling

Ensure the box-sizing is set to border-box for the means of measuring the tour target.

* {
  box-sizing: border-box;
}

Ensure the body has a position of relative.

body {
  position: relative;
}

API Reference

Props

Root

ActionTrigger

Renders a <button> element.

Arrow

Renders a <div> element.

ArrowTip

Renders a <div> element.

Backdrop

Renders a <div> element.

CloseTrigger

Renders a <button> element.

Content

Renders a <div> element.

Control

Renders a <div> element.

Description

Renders a <div> element.

Positioner

Renders a <div> element.

ProgressText

Renders a <div> element.

Spotlight

Renders a <div> element.

Title

Renders a <h2> element.

Context

API