Tour

Overlay

Feedback

Guided walkthrough component with spotlight highlighting for onboarding.

Preview

Create a guided tour with multiple steps

Step 1

First tour target

Step 2

Second tour target

Step 3

Third tour target

Step 4

Fourth tour target

Props

Component API reference

Tour

Prop	Type	Default	Description
`steps*`	`TourStep[]`	—	Array of tour steps
`open`	`boolean`	`false`	Whether tour is visible
`current`	`number`	`0`	Current step index
`onChange`	`(current: number) => void`	—	Callback when step changes
`onClose`	`() => void`	—	Callback when tour closes
`mask`	`boolean`	`true`	Show spotlight mask
`type`	`'default' \| 'primary'`	`'default'`	Tour style variant

TourStep

Prop	Type	Default	Description
`target*`	`string \| RefObject<HTMLElement>`	—	CSS selector or ref to target
`title*`	`string`	—	Step title
`description*`	`string`	—	Step description
`placement`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'bottom'`	Popover placement
`icon`	`ComponentType`	—	Optional icon component
`cover`	`string`	—	Optional cover image URL

Usage

Import and implementation examples

import { Tour, type TourStep } from '@/components/ui/tour'
import { useRef, useState } from 'react'
import { Lightbulb } from 'lucide-react'

function MyComponent() {
  const [open, setOpen] = useState(false)
  const [current, setCurrent] = useState(0)
  const step1Ref = useRef<HTMLDivElement>(null)

  const steps: TourStep[] = [
    {
      target: step1Ref,
      title: 'Welcome',
      description: 'This is your first step.',
      placement: 'bottom',
      icon: Lightbulb,
    },
    // ... more steps
  ]

  return (
    <>
      <div ref={step1Ref}>Target Element</div>
      <button onClick={() => setOpen(true)}>Start Tour</button>

      <Tour
        steps={steps}
        open={open}
        current={current}
        onChange={setCurrent}
        onClose={() => setOpen(false)}
      />
    </>
  )
}

Features

Built-in functionality

Spotlight mask: SVG spotlight highlighting target elements
Auto positioning: Smart placement around target elements
Custom icons: Add icons to each tour step
Step navigation: Next/Previous buttons with progress
Ref or selector: Target elements by ref or CSS selector
Cover images: Optional images in tour steps
Two styles: Default and primary styling options
Dark mode: Full dark mode support

Accessibility

Accessibility considerations

ARIA Attributes

role="dialog" for tour popoveraria-modal="true" when openaria-labelledby for step titlearia-describedby for step description

Keyboard Navigation

Key	Action
`Escape`	Close tour
`Tab`	Navigate between buttons
`Enter`	Activate focused button

Notes

Focus management during tour
Screen reader announces each step
Progress indicator is accessible

Related Components

Popover Dialog Steps