GuidedTour

Purpose

GuidedTour provides an interactive walkthrough experience:

• Spotlight highlighting of target elements
• Step-by-step navigation
• Keyboard navigation support
• Positioned tooltips with arrows

When to use

Use GuidedTour for:

• New user onboarding
• Feature discovery
• Complex workflow guidance
• First-time setup wizards

Basic usage

import { GuidedTour, type TourStep } from '@/shared/ui/components/GuidedTour'

const steps: TourStep[] = [
  {
    target: '#sidebar-nav',
    title: 'Navigation',
    content: 'Use the sidebar to navigate between sections.',
    position: 'right',
  },
  {
    target: '#create-button',
    title: 'Create New',
    content: 'Click here to create a new item.',
    position: 'bottom',
  },
  {
    target: '#search-input',
    title: 'Search',
    content: 'Use search to find items quickly.',
    position: 'bottom',
  },
]

export function OnboardingTour() {
  const [isOpen, setIsOpen] = useState(true)

  return (
    <GuidedTour
      steps={steps}
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
      onFinish={() => {
        setIsOpen(false)
        // Mark onboarding complete
      }}
    />
  )
}

Props

GuidedTourProps

Prop	Type	Required	Description
steps	TourStep[]	Yes	Array of tour steps
isOpen	boolean	Yes	Whether tour is active
onClose	() => void	Yes	Called when tour is dismissed
onFinish	() => void	Yes	Called when tour completes
className	string	No	Additional class

TourStep

Property	Type	Required	Description
target	string	Yes	CSS selector for target element
title	string	Yes	Step title
content	ReactNode	Yes	Step description
position	'top' | 'right' | 'bottom' | 'left'	No	Tooltip position

Keyboard navigation

Key	Action
Escape	Close tour
Enter / →	Next step
←	Previous step

Notes

• Target elements must exist in the DOM when the tour starts
• The spotlight uses a neon glow effect for visibility
• Tour progress is shown as "X / Y" in the tooltip
• Consider persisting completion state to avoid showing repeatedly