API Reference

SpotlightProviderProps

Props for the <SpotlightProvider> component that wraps your application and manages all tour state.

Prop	Type	Default	Description
`children`	`ReactNode`	--	Your application content
`theme`	`'light' \| 'dark' \| 'auto' \| SpotlightTheme`	`'light'`	Theme preset or custom theme object
`overlayColor`	`string`	`'rgba(0, 0, 0, 0.5)'`	Overlay background color (with alpha)
`transitionDuration`	`number`	`300`	Transition duration in milliseconds
`escToDismiss`	`boolean`	`true`	Whether pressing Escape dismisses the tour
`overlayClickToDismiss`	`boolean`	`true`	Whether clicking the overlay dismisses the tour
`showProgress`	`boolean`	`true`	Whether to show a progress bar
`showSkip`	`boolean`	`true`	Whether to show a skip button
`labels`	`SpotlightLabels`	--	Custom labels for i18n
`onComplete`	`(tourId: string) => void`	--	Called when any tour completes
`onSkip`	`(tourId: string, stepIndex: number) => void`	--	Called when any tour is skipped
`onStateChange`	`(tourId: string, state: TourState) => void`	--	Called with tour state for persistence
`initialState`	`Record<string, TourState>`	--	Initial state for restoring persisted tours
`waitForElementTimeout`	`number`	`5000`	Default max time (ms) to wait for a step's `target` to appear in the DOM before skipping to the next step. Overridable per-step via `SpotlightStep.timeout`
`persist`	`boolean \| SpotlightStorage`	--	Enable cross-navigation persistence. `true` uses `localStorage`; pass a custom `SpotlightStorage` for other backends. Off by default
`persistKey`	`string`	`'react-tourlight'`	Storage key used when `persist` is enabled
`persistMaxAge`	`number`	--	Discard persisted state older than this many ms (staleness guard)
`resume`	`boolean`	`true`	Auto-resume a persisted, still-active tour on mount
`navigate`	`(path: string) => void`	--	Called with a step's `route` when it doesn't match the current location. Plug in your router
`isRouteActive`	`(route: string, pathname: string) => boolean`	built-in	Custom route matcher (overrides the exact / `:param` / `*` default)

SpotlightTourProps

Props for the <SpotlightTour> component that registers a tour's steps with the provider.

Prop	Type	Default	Description
`id`	`string`	--	Unique identifier for this tour
`steps`	`SpotlightStep[]`	--	Array of step configurations
`onComplete`	`() => void`	--	Called when this tour completes
`onSkip`	`(stepIndex: number) => void`	--	Called when this tour is skipped
`renderTooltip`	`(props: TooltipRenderProps) => ReactNode`	--	Custom tooltip render function

SpotlightStep

Configuration for a single tour step.

Prop	Type	Default	Description
`target`	`string \| RefObject<HTMLElement \| null>`	--	CSS selector or React ref for the target element
`title`	`string`	--	Step title shown in the tooltip header
`content`	`ReactNode`	--	Step content -- string or React element
`placement`	`'top' \| 'bottom' \| 'left' \| 'right' \| 'auto'`	`'auto'`	Tooltip placement relative to target
`spotlightPadding`	`number`	--	Padding around the spotlight cutout (px)
`spotlightRadius`	`number`	--	Border radius of the spotlight cutout (px)
`action`	`{ label: string; onClick: () => void }`	--	Optional CTA button inside the tooltip
`when`	`() => boolean \| Promise<boolean>`	--	Condition -- step is skipped if this returns `false`
`onBeforeShow`	`() => void \| Promise<void>`	--	Called before the step is shown (can be async)
`onAfterShow`	`() => void`	--	Called after the step is visible
`onHide`	`() => void`	--	Called when the step is hidden
`disableOverlayClose`	`boolean`	`false`	Prevent overlay click from dismissing
`interactive`	`boolean`	`false`	Make the spotlight hole genuinely transparent to all pointer/keyboard/focus events, so the user can interact with the real highlighted element (typing, hovering, dragging, scrolling)
`advanceOn`	`{ event: string; selector?: string }`	--	Auto-advance the tour when `event` fires on the target (or a descendant matching `selector`). Implies `interactive`
`route`	`string`	--	The path this step lives on. When advancing to it on a different route, the provider calls `navigate(route)` and waits for the target there. Supports exact, `:param`, and trailing `*`
`onBeforeStep`	`() => void \| Promise<void>`	--	Escape hatch run before the step's target is resolved (and before `route` navigation). Awaited
`timeout`	`number`	`5000`	Max time (ms) to wait for `target` to appear in the DOM before skipping this step. Overrides `waitForElementTimeout` on the provider

SpotlightHighlightProps

Props for the <SpotlightHighlight> component for single-element highlights.

Prop	Type	Default	Description
`target`	`string \| RefObject<HTMLElement \| null>`	--	CSS selector or React ref for the target element
`title`	`string`	--	Tooltip title
`content`	`ReactNode`	--	Tooltip content
`active`	`boolean`	`true`	Whether the highlight is currently visible
`placement`	`'top' \| 'bottom' \| 'left' \| 'right' \| 'auto'`	`'auto'`	Tooltip placement relative to target
`spotlightPadding`	`number`	--	Padding around the spotlight cutout (px)
`spotlightRadius`	`number`	--	Border radius of the spotlight cutout (px)
`onDismiss`	`() => void`	--	Called when the highlight is dismissed

useSpotlight()

Hook to access spotlight context. Must be used within a <SpotlightProvider>.

const spotlight = useSpotlight()

Return value: SpotlightContextValue

Property	Type	Description
`start`	`(tourId: string) => void`	Start a tour by its ID
`stop`	`() => void`	Stop the currently active tour
`next`	`() => void`	Advance to the next step
`previous`	`() => void`	Go back to the previous step
`skip`	`() => void`	Skip the current tour
`goToStep`	`(index: number) => void`	Jump to a specific step by index
`isActive`	`boolean`	Whether a tour or highlight is currently active
`activeTourId`	`string \| null`	ID of the currently active tour, or `null`
`currentStep`	`number`	Index of the current step (zero-based)
`totalSteps`	`number`	Total number of steps in the active tour
`registerTour`	`(id, steps, callbacks?) => void`	Register a tour (used internally by SpotlightTour)
`unregisterTour`	`(id: string) => void`	Unregister a tour (used internally)
`highlight`	`(step: SpotlightStep) => void`	Show a single-element highlight
`dismissHighlight`	`() => void`	Dismiss the active highlight

useSpotlightControl()

A convenience hook that wraps useSpotlight() with memoized callbacks. Provides the same control methods without the internal registration methods.

const spotlight = useSpotlightControl()

Return value: SpotlightControl

Property	Type	Description
`start`	`(tourId: string) => void`	Start a tour by its ID
`stop`	`() => void`	Stop the currently active tour
`next`	`() => void`	Advance to the next step
`previous`	`() => void`	Go back to the previous step
`skip`	`() => void`	Skip the current tour
`goToStep`	`(index: number) => void`	Jump to a specific step by index
`highlight`	`(step: SpotlightStep) => void`	Show a single-element highlight
`dismissHighlight`	`() => void`	Dismiss the active highlight
`isActive`	`boolean`	Whether a tour or highlight is currently active

useSpotlightTarget()

Hook that returns a RefObject to attach to a target element. Use this instead of CSS selectors when you want type-safe, refactor-friendly targets.

const ref = useSpotlightTarget<HTMLInputElement>()

// Use in steps:
{ target: ref, title: 'Search', content: '...' }

// Attach to element:
<input ref={ref} />

Return value

Type	Description
`RefObject<T \| null>`	A React ref to attach to the target DOM element

SpotlightLabels

Labels for i18n. All properties are optional and fall back to English defaults.

Property	Type	Default	Description
`next`	`string`	`'Next'`	Next button label
`previous`	`string`	`'Previous'`	Previous button label
`skip`	`string`	`'Skip'`	Skip button label
`done`	`string`	`'Done'`	Done button label (last step)
`close`	`string`	`'Close'`	Close button aria-label
`stepOf`	`(current: number, total: number) => string`	`'Step {n} of {m}'`	Step counter format function

TooltipRenderProps

Props passed to the renderTooltip function on <SpotlightTour>.

Property	Type	Description
`step`	`SpotlightStep`	The current step configuration
`next`	`() => void`	Advance to the next step or complete the tour
`previous`	`() => void`	Go back to the previous step
`skip`	`() => void`	Skip the tour
`currentIndex`	`number`	Zero-based index of the current step
`totalSteps`	`number`	Total number of steps

TourState

Persisted state for a tour, provided via the onStateChange callback.

Property	Type	Description
`status`	`'idle' \| 'active' \| 'completed'`	Current lifecycle status
`currentStepIndex`	`number`	Index of the current step (when active)
`seenSteps`	`number[]`	Indices of steps the user has seen
`completedAt`	`number \| undefined`	Timestamp when the tour was completed
`skippedAt`	`{ stepIndex: number; timestamp: number } \| undefined`	Step index and timestamp when the tour was skipped

Headless core (`react-tourlight/core`)

The react-tourlight/core subpath exports the entire unstyled engine with no CSS, no default tooltip, and no Floating UI. See the Headless Core guide. Key exports:

Export	Description
`useTour(options)`	Headless controller hook. Returns `{ status, isActive, currentIndex, totalSteps, step, targetElement, rect, clipPath, isResolving, start, stop, next, previous, skip, goToStep }`.
`isRouteActive` / `getCurrentPath`	Router-agnostic path matcher and current-pathname helper.
`createMemoryStorage`	In-memory `SpotlightStorage` adapter.
`loadPersistedTours` / `savePersistedTour` / `clearPersistedTour` / `isPersistedStateFresh` / `resolveStorage`	Persistence helpers.
`createFocusTrap` / `setInert` / `getStepAriaLabel` / `createKeyboardHandler` / `scrollIntoView`	Focus & a11y utilities.

All of the engine primitives below (plus useTour, isRouteActive, getCurrentPath, and createMemoryStorage) are also re-exported from the main react-tourlight entry for convenience.

UseTourOptions

Property	Type	Default	Description
`steps`	`SpotlightStep[]`	--	Steps to drive through
`onComplete`	`() => void`	--	Called when the tour finishes
`onSkip`	`(stepIndex: number) => void`	--	Called when the tour is skipped
`onStateChange`	`(state: TourState) => void`	--	Called on every transition
`initialState`	`Partial<TourState>`	--	Seed state, e.g. from persistence
`waitForElementTimeout`	`number`	`5000`	Default wait for a step target
`navigate`	`(path: string) => void`	--	Route-aware navigation
`isRouteActive`	`(route, pathname) => boolean`	built-in	Custom matcher
`autoScroll`	`boolean`	`true`	Scroll the target into view before showing

Engine primitives

Advanced/low-level exports for building a fully custom tour UI. Most consumers won't need these directly — SpotlightProvider and SpotlightTour use them internally.

Export	Signature	Description
`createTourStateMachine`	`(options: TourStateMachineOptions) => TourStateMachineActions`	Closure-based state machine driving step/lifecycle transitions (`start`, `stop`, `next`, `previous`, `skip`, `goToStep`, `getState`, `subscribe`). No UI or DOM access.
`waitForElement`	`(target: string, options?: WaitForElementOptions) => Promise<HTMLElement \| null>`	Waits for a CSS selector to match an element in the DOM via `MutationObserver`. Resolves with the element, or `null` after `options.timeout` (default `5000`ms) elapses.
`resolveTarget`	`(target: string \| RefObject<HTMLElement \| null>) => HTMLElement \| null`	Resolves a step's `target` (CSS selector or ref) to a DOM element, or `null` if not found.
`getTargetRect`	`(element: HTMLElement) => ElementRect`	Returns an element's `getBoundingClientRect()` as a plain `{ x, y, width, height }` object.
`measureElement`	`(element: HTMLElement, padding?: number) => ElementRect`	Like `getTargetRect`, but expands the rect by `padding` pixels on all sides.
`generateClipPath`	`(rect: ElementRect, padding: number, radius: number) => string`	Builds the `clip-path: path(evenodd, ...)` value used for the spotlight cutout around `rect`.

TourStateMachineOptions

Property	Type	Description
`steps`	`SpotlightStep[]`	Steps to drive through
`initialState`	`Partial<TourState>`	Optional initial state (e.g. to resume a persisted tour)
`onComplete`	`() => void`	Called when the tour finishes
`onSkip`	`(stepIndex: number) => void`	Called when the tour is skipped
`onStateChange`	`(state: TourState) => void`	Called on every state transition

WaitForElementOptions

Property	Type	Default	Description
`timeout`	`number`	`5000`	Maximum time to wait, in milliseconds

SpotlightTheme

Full theme interface. See the Customization page for usage examples.

Section	Properties
`overlay`	`background: string`
`tooltip`	`background: string`, `color: string`, `borderRadius: string`, `boxShadow: string`, `padding: string`, `maxWidth: string`
`title`	`fontSize: string`, `fontWeight: string`, `color: string`, `marginBottom: string`
`content`	`fontSize: string`, `color: string`, `lineHeight: string`
`button`	`background: string`, `color: string`, `borderRadius: string`, `padding: string`, `fontSize: string`, `fontWeight: string`, `border: string`, `cursor: string`, `hoverBackground: string`
`buttonSecondary`	`background: string`, `color: string`, `border: string`, `hoverBackground: string`
`progress`	`background: string`, `fill: string`, `height: string`, `borderRadius: string`
`arrow`	`fill: string`
`closeButton`	`color: string`, `hoverColor: string`

On this page