React Joyride

React Joyride v3

Create guided tours in React apps. Two public APIs: the useJoyride() hook (recommended) and the <Joyride> component.

Online docs: https://v3.react-joyride.com

Quick Start

Using the hook (recommended)

import { useJoyride, STATUS, Status } from 'react-joyride';

function App() {
  const { Tour } = useJoyride({
    continuous: true,
    run: true,
    steps: [
      { target: '.my-element', content: 'This is the first step', title: 'Welcome' },
      { target: '#sidebar', content: 'Navigate here', placement: 'right' },
    ],
    onEvent: (data) => {
      if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {
        // Tour ended
      }
    },
  });

  return <div>{Tour}{/* rest of app */}</div>;
}

Using the component

import { Joyride, STATUS, Status } from 'react-joyride';

function App() {
  return (
    <Joyride
      continuous
      run={true}
      steps={[
        { target: '.my-element', content: 'First step' },
        { target: '#sidebar', content: 'Second step' },
      ]}
      onEvent={(data) => {
        if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {
          // Tour ended
        }
      }}
    />
  );
}

The hook returns { controls, failures, on, state, step, Tour }. Render Tour in your JSX.

Docs: https://v3.react-joyride.com/docs/getting-started

Core Concepts

The tour has two state dimensions:

Tour Status: idle -> ready -> waiting -> running <-> paused -> finished | skipped

• idle: No steps loaded
• ready: Steps loaded, waiting for run: true
• waiting: run=true but steps loading async (transitions to running when steps arrive)
• running: Tour active
• paused: Tour paused (controlled mode at COMPLETE, or stop() called)
• finished / skipped: Tour ended

Step Lifecycle (per step): init -> ready -> beacon_before -> beacon -> tooltip_before -> tooltip -> complete

• *_before phases: scrolling and positioning happen here
• beacon: Pulsing indicator shown (skipped when continuous + navigating, skipBeacon, or placement: 'center')
• tooltip: The tooltip is visible and interactive

Docs: https://v3.react-joyride.com/docs/how-it-works

Step Configuration

Each step requires target and content. All other fields are optional.

{
  target: '.my-element',       // CSS selector, HTMLElement, React ref, or () => HTMLElement
  content: 'Step body text',   // ReactNode
  title: 'Optional title',    // ReactNode
  placement: 'bottom',        // Default. Also: top, left, right, *-start, *-end, auto, center
  id: 'unique-id',            // Optional identifier
  data: { custom: 'data' },   // Attached to event callbacks
}

Target types

// CSS selector
{ target: '.sidebar-nav' }
// HTMLElement
{ target: document.getElementById('my-el') }
// React ref
const ref = useRef(null);
{ target: ref }
// Function (evaluated each lifecycle)
{ target: () => document.querySelector('.dynamic-element') }

Common step options (override per-step)

All Options fields can be set globally via options prop or per-step. Per-step values override global.

Docs: https://v3.react-joyride.com/docs/step | https://v3.react-joyride.com/docs/props/options

Uncontrolled vs Controlled

Uncontrolled (default — strongly preferred)

The tour manages step navigation internally. This is the right choice for most use cases.

The library handles async transitions for you. If a step needs to wait for a UI change (dropdown opening, data loading, animation), use before hooks — the tour waits for the promise to resolve before showing the step. If a target element isn't in the DOM yet, targetWaitTimeout (default: 1000ms) handles polling for it. You do NOT need controlled mode for these cases.

const { Tour } = useJoyride({
  continuous: true,
  run: isRunning,
  steps: [
    { target: '.nav', content: 'Navigation' },
    {
      target: '.dropdown-item',
      content: 'Inside the dropdown',
      before: () => {
        // Open dropdown and wait for animation — tour waits automatically
        openDropdown();
        return new Promise(resolve => setTimeout(resolve, 300));
      },
      after: () => closeDropdown(), // Clean up after step (fire-and-forget)
    },
    { target: '.main-content', content: 'Main content' },
  ],
  onEvent: (data) => {
    if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {
      setIsRunning(false);
    }
  },
});

Controlled (with stepIndex) — use sparingly

Only use controlled mode when the parent genuinely needs to manage the step index externally (e.g., syncing with URL params, external state machines, or complex multi-component coordination that before/after hooks can't handle).

const [stepIndex, setStepIndex] = useState(0);
const [run, setRun] = useState(true);

const { Tour } = useJoyride({
  continuous: true,
  run,
  stepIndex,  // This makes it controlled
  steps,
  onEvent: (data) => {
    const { action, index, status, type } = data;

    if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(status)) {
      setRun(false);
      return;
    }

    if (type === 'step:after' || type === 'error:target_not_found') {
      setStepIndex(index + (action === 'prev' ? -1 : 1));
    }
  },
});

Controlled mode rules:

• go() and reset() are disabled (logged warning)
• You must update stepIndex in response to events
• The tour pauses at COMPLETE — you must advance it
• Prefer uncontrolled mode with before/after hooks unless you have a strong reason for external index management

Event System

onEvent callback

onEvent: (data: EventData, controls: Controls) => void

The data object contains the full tour state plus event-specific fields. The controls object lets you programmatically control the tour.

Event types (in order per step)

Event subscription with on()

const { on, Tour } = useJoyride({ ... });

useEffect(() => {
  const unsubscribe = on('tooltip', (data, controls) => {
    analytics.track('tour_step_viewed', { step: data.index });
  });
  return unsubscribe;
}, [on]);

Docs: https://v3.react-joyride.com/docs/events

Controls

Available via useJoyride() return value or onEvent second argument:

Docs: https://v3.react-joyride.com/docs/hook

Styling & Theming

Three layers of customization (from simple to full control):

1. Color options (simplest)

options: {
  primaryColor: '#1976d2',      // Buttons and beacon
  backgroundColor: '#1a1a2e',   // Tooltip background
  textColor: '#ffffff',         // Tooltip text
  overlayColor: 'rgba(0,0,0,0.7)', // Overlay backdrop
  arrowColor: '#1a1a2e',        // Arrow (match background)
}

2. Styles override

styles: {
  tooltip: { borderRadius: 12 },
  buttonPrimary: { backgroundColor: '#1976d2' },
  buttonBack: { color: '#666' },
  spotlight: { borderRadius: 8 },
}

Style keys: arrow, beacon, beaconInner, beaconOuter, beaconWrapper, buttonBack, buttonClose, buttonPrimary, buttonSkip, floater, loader, overlay, tooltip, tooltipContainer, tooltipContent, tooltipFooter, tooltipFooterSpacer, tooltipTitle

3. Custom components (full control)

See next section.

Docs: https://v3.react-joyride.com/docs/props/styles

Custom Components

Replace any UI component via props. Each receives render props with step data and button handlers.

Custom Tooltip

import type { TooltipRenderProps } from 'react-joyride';

function MyTooltip({ backProps, index, primaryProps, size, skipProps, step, tooltipProps }: TooltipRenderProps) {
  return (
    <div {...tooltipProps} style={{ background: '#fff', padding: 16, borderRadius: 8, width: step.width }}>
      {step.title && <h3>{step.title}</h3>}
      <div>{step.content}</div>
      <div>
        {index > 0 && <button {...backProps}>Back</button>}
        <button {...primaryProps}>Next</button>
      </div>
    </div>
  );
}

// Usage
<Joyride tooltipComponent={MyTooltip} ... />

Important: Spread tooltipProps on the container (sets role="dialog" and aria-modal). Spread button props (backProps, primaryProps, closeProps, skipProps) on buttons for correct action handling.

Custom Beacon

Must render a <span> (placed inside a <button> wrapper). Receives BeaconRenderProps: { continuous, index, isLastStep, size, step }.

Custom Arrow

Receives ArrowRenderProps: { base, placement, size }.

Custom Loader

Receives LoaderRenderProps: { step }. Set to null to disable the loader.

Docs: https://v3.react-joyride.com/docs/custom-components

Problem → Solution Guide

Common Gotchas & Debugging

Use debug: true first

The debug prop is the most powerful troubleshooting tool. It logs detailed lifecycle transitions, state changes, and event emissions to the console. Always start here when something isn't working.

<Joyride debug={true} ... />
// or
useJoyride({ debug: true, ... })

The console output shows exactly which lifecycle phase the tour reaches, what actions are firing, and where it gets stuck.

Tour not starting

• Check run={true} is set
• Verify steps array is not empty and steps have valid target + content
• For SSR: use <Joyride> component (auto-guards DOM access) or check typeof window !== 'undefined'

Target not found

• Test selector in console: document.querySelector('.your-selector')
• Element must be visible (not display: none, visibility: hidden, or zero dimensions)
• If element mounts later, increase targetWaitTimeout (default: 1000ms)
• Set targetWaitTimeout: 0 to skip waiting entirely
• In uncontrolled mode, missing targets auto-advance; in controlled mode, handle error:target_not_found event

Tooltip never appears / overlay flashes

• Add debug: true and check the console to see which lifecycle phase is reached
• Verify the target element is in the viewport or scrollable
• Check for CSS overflow: hidden on ancestors clipping the target
• If using portals or modals, the target may not be accessible

Controlled mode stuck

• First question: do you actually need controlled mode? Most async needs are solved with before/after hooks in uncontrolled mode
• If controlled: you MUST update stepIndex in your onEvent handler when type === 'step:after'
• Handle both forward (action !== 'prev') and backward (action === 'prev') navigation
• Also handle error:target_not_found to skip broken steps
• go() and reset() don't work in controlled mode

Before hook timeout

• Default beforeTimeout is 5000ms — increase if your async operation takes longer
• Set beforeTimeout: 0 for no timeout
• The loader appears after loaderDelay (300ms) while waiting

Scroll issues

• Use scrollTarget to scroll to a different element than the tooltip target
• Adjust scrollOffset (default: 20px) for headers or fixed elements
• Set skipScroll: true to disable auto-scrolling for a step
• scrollToFirstStep: false by default — set to true if first step is off-screen

Center placement

• Use placement: 'center' with target: 'body' for modal-style centered tooltips
• Center placement automatically hides the beacon and arrow

Imports

// Named exports only (no default export in v3)
import { Joyride, useJoyride } from 'react-joyride';

// Constants for type-safe comparisons
import { ACTIONS, EVENTS, LIFECYCLE, ORIGIN, STATUS } from 'react-joyride';

// Types
import type { Step, Props, EventData, Controls, TooltipRenderProps } from 'react-joyride';

Docs: https://v3.react-joyride.com/docs/exports

Reference Files

Read these for complete API details:

• references/api-props-options.md — Full Props, Options (all 30+ fields with defaults), Locale, FloatingOptions, Styles types
• references/api-step-state-controls.md — Step, StepMerged, StepTarget, State, Controls (all 10 methods), UseJoyrideReturn, StepFailure
• references/api-events-components.md — All 13 event types, ACTIONS/LIFECYCLE/STATUS/ORIGIN constants, EventData, custom component render props
• references/patterns.md — Complete working examples: controlled mode, before/after hooks, custom tooltip, event subscription, dynamic steps

Events, Constants, Custom Components

Constants

ACTIONS

const ACTIONS = {
  INIT: 'init',
  START: 'start',
  STOP: 'stop',
  RESET: 'reset',
  PREV: 'prev',
  NEXT: 'next',
  GO: 'go',
  CLOSE: 'close',
  SKIP: 'skip',
  UPDATE: 'update',
  COMPLETE: 'complete',
} as const;

EVENTS

const EVENTS = {
  TOUR_START: 'tour:start',
  STEP_BEFORE_HOOK: 'step:before_hook',
  STEP_BEFORE: 'step:before',
  SCROLL_START: 'scroll:start',
  SCROLL_END: 'scroll:end',
  BEACON: 'beacon',
  TOOLTIP: 'tooltip',
  STEP_AFTER: 'step:after',
  STEP_AFTER_HOOK: 'step:after_hook',
  TOUR_END: 'tour:end',
  TOUR_STATUS: 'tour:status',
  TARGET_NOT_FOUND: 'error:target_not_found',
  ERROR: 'error',
} as const;

LIFECYCLE

const LIFECYCLE = {
  INIT: 'init',
  READY: 'ready',
  BEACON_BEFORE: 'beacon_before',
  BEACON: 'beacon',
  TOOLTIP_BEFORE: 'tooltip_before',
  TOOLTIP: 'tooltip',
  COMPLETE: 'complete',
} as const;

STATUS

const STATUS = {
  IDLE: 'idle',
  READY: 'ready',
  WAITING: 'waiting',
  RUNNING: 'running',
  PAUSED: 'paused',
  SKIPPED: 'skipped',
  FINISHED: 'finished',
} as const;

ORIGIN

const ORIGIN = {
  BUTTON_CLOSE: 'button_close',
  BUTTON_SKIP: 'button_skip',
  BUTTON_PRIMARY: 'button_primary',
  KEYBOARD: 'keyboard',
  OVERLAY: 'overlay',
} as const;

Event Types

EventData

The full payload passed to onEvent and event subscribers:

type EventData = TourData & {
  error: Error | null;         // Only for 'error' events
  scroll: ScrollData | null;   // Only for 'scroll:start' / 'scroll:end'
  scrolling: boolean;
  type: Events;                // The event type (discriminator)
  waiting: boolean;
}

TourData

Base payload (also passed to before and after hooks):

interface TourData {
  action: Actions;
  controlled: boolean;
  index: number;
  lifecycle: Lifecycle;
  origin: Origin | null;
  size: number;
  status: Status;
  step: StepMerged;
}

EventHandler

type EventHandler = (data: EventData, controls: Controls) => void;

ScrollData

type ScrollData = {
  duration: number;     // Scroll duration in ms
  element: Element;     // Element being scrolled
  initial: number;      // Scroll position before
  target: number;       // Computed scroll destination
}

Event Flow (per step)

tour:start (once)
  |
  v
step:before_hook  (if before hook exists)
  |
  v
step:before  (target found, step about to render)
  |
  v
scroll:start / scroll:end  (if scrolling needed)
  |
  v
beacon  (if beacon shown) OR tooltip  (if beacon skipped)
  |
  v  (user clicks beacon)
tooltip
  |
  v  (user clicks next/prev/close/skip)
step:after
  |
  v
step:after_hook  (if after hook exists)
  |
  v  (next step or tour end)
tour:end  (when finished/skipped)

Custom Component Render Props

TooltipRenderProps

type TooltipRenderProps = {
  // Tour state
  continuous: boolean;
  index: number;
  isLastStep: boolean;
  size: number;
  step: StepMerged;

  // Button props (spread on button elements)
  backProps: {
    'aria-label': string;
    'data-action': string;
    onClick: MouseEventHandler<HTMLElement>;
    role: string;
    title: string;
  };
  closeProps: { /* same shape */ };
  primaryProps: { /* same shape */ };
  skipProps: { /* same shape */ };

  // Container props (spread on tooltip wrapper)
  tooltipProps: {
    'aria-modal': boolean;
    role: string;  // 'dialog'
  };

  // Tour controls
  controls: Controls;
}

Important: Always spread tooltipProps on the root element and button props on their respective buttons. This ensures correct accessibility attributes and action handling.

BeaconRenderProps

type BeaconRenderProps = {
  continuous: boolean;
  index: number;
  isLastStep: boolean;
  size: number;
  step: StepMerged;
}

Must render a <span> since it's placed inside a <button> wrapper.

ArrowRenderProps

type ArrowRenderProps = {
  base: number;          // Arrow base width
  placement: Placement;  // Computed placement
  size: number;          // Arrow height
}

LoaderRenderProps

type LoaderRenderProps = {
  step: StepMerged;
}

Set loaderComponent={null} on Props or Step to disable the loader entirely.

Docs: https://v3.react-joyride.com/docs/custom-components

Props, Options, Locale, FloatingOptions, Styles

Props

type Props = SharedProps & {
  continuous?: boolean;        // Sequential play with Next button (default: false)
  debug?: boolean;             // Log to console (default: false)
  initialStepIndex?: number;   // Start index for uncontrolled mode (default: 0)
  nonce?: string;              // CSP nonce for inline styles
  onEvent?: EventHandler;      // (data: EventData, controls: Controls) => void
  options?: Partial<Options>;  // Default options for all steps
  portalElement?: string | HTMLElement; // Render tooltip into this element
  run?: boolean;               // Start/stop tour (default: false)
  scrollToFirstStep?: boolean; // Scroll to first step on start (default: false)
  stepIndex?: number;          // Controlled mode: manages step index externally
  steps: Array<Step>;          // Required: tour steps
}

SharedProps

Inherited by both Props and Step:

type SharedProps = {
  arrowComponent?: ElementType<ArrowRenderProps>;
  beaconComponent?: ElementType<BeaconRenderProps>;
  floatingOptions?: Partial<FloatingOptions>;
  loaderComponent?: ElementType<LoaderRenderProps> | null; // null disables loader
  locale?: Locale;
  styles?: PartialDeep<Styles>;
  tooltipComponent?: ElementType<TooltipRenderProps>;
}

Options

All fields can be set globally via options prop or per-step (step overrides global).

Appearance

Arrow

Beacon

Overlay & Spotlight

interface SpotlightPadding { top?: number; right?: number; bottom?: number; left?: number; }

Buttons & Interactions

ButtonType = 'back' | 'close' | 'primary' | 'skip'

Scroll

Timing & Async

Locale

interface Locale {
  back?: ReactNode;              // 'Back'
  close?: ReactNode;             // 'Close'
  last?: ReactNode;              // 'Last'
  next?: ReactNode;              // 'Next'
  nextWithProgress?: ReactNode;  // 'Next ({current} of {total})'
  open?: ReactNode;              // 'Open the dialog'
  skip?: ReactNode;              // 'Skip'
}

{current} and {total} are placeholder strings replaced at render time in nextWithProgress.

FloatingOptions

Controls @floating-ui/react-dom positioning:

interface FloatingOptions {
  autoUpdate?: Partial<AutoUpdateOptions>;     // Auto-reposition options
  beaconOptions?: { offset?: number };         // Beacon offset (default: -18)
  flipOptions?: Partial<FlipOptions> | false;  // Flip middleware (false to disable)
  hideArrow?: boolean;                         // Hide arrow (default: false)
  middleware?: Array<Middleware>;               // Additional Floating UI middleware
  onPosition?: (data: PositionData) => void;   // Position callback
  shiftOptions?: Partial<ShiftOptions>;        // Shift middleware options
  strategy?: 'fixed' | 'absolute';             // Auto-detected from step.isFixed
}

Docs: https://v3.react-joyride.com/docs/props/floating-options

Styles

Override CSS for any UI element:

interface Styles {
  arrow: CSSProperties;
  beacon: CSSProperties;
  beaconInner: CSSProperties;
  beaconOuter: CSSProperties;
  beaconWrapper: CSSProperties;
  buttonBack: CSSProperties;
  buttonClose: CSSProperties;
  buttonPrimary: CSSProperties;
  buttonSkip: CSSProperties;
  floater: CSSProperties;
  loader: CSSProperties;
  overlay: CSSProperties;
  tooltip: CSSProperties;
  tooltipContainer: CSSProperties;
  tooltipContent: CSSProperties;
  tooltipFooter: CSSProperties;
  tooltipFooterSpacer: CSSProperties;
  tooltipTitle: CSSProperties;
}

Use PartialDeep<Styles> — only override what you need.

Docs: https://v3.react-joyride.com/docs/props/styles

Step, State, Controls

Step

A single step provided by the user. Extends SharedProps and Partial<Options>.

type Step = SharedProps & Partial<Options> & {
  // Required
  content: ReactNode;                           // Tooltip body
  target: StepTarget;                           // Element to highlight

  // Optional
  id?: string;                                  // Unique identifier
  title?: ReactNode;                            // Tooltip title
  data?: any;                                   // Custom data (passed to callbacks)

  // Positioning
  placement?: Placement | 'auto' | 'center';   // Default: 'bottom'
  beaconPlacement?: Placement;                  // Beacon-specific placement
  isFixed?: boolean;                            // Force fixed positioning (default: false)

  // Alternate targets
  scrollTarget?: StepTarget;                    // Scroll to this instead of target
  spotlightTarget?: StepTarget;                 // Highlight this instead of target
}

All Options fields (see api-props-options.md) are also valid on Step for per-step overrides.

StepTarget

Four ways to specify a target element:

type StepTarget =
  | string                              // CSS selector
  | HTMLElement                         // Direct element reference
  | RefObject<HTMLElement | null>       // React ref
  | (() => HTMLElement | null);         // Function (re-evaluated each lifecycle)

StepMerged

The normalized step after defaults are applied. All Options fields become required, plus:

• spotlightPadding: Required<SpotlightPadding> (always { top, right, bottom, left })
• styles: Styles (fully resolved)

This is what you receive in event callbacks and custom component props.

State

type State = {
  action: Actions;         // What triggered the update (init, start, next, prev, etc.)
  controlled: boolean;     // true when stepIndex prop is set
  index: number;           // Current step index
  lifecycle: Lifecycle;     // Step rendering phase
  origin: Origin | null;   // UI element that triggered action
  scrolling: boolean;      // Scroll animation in progress
  size: number;            // Total number of steps
  status: Status;          // Tour status (idle, ready, running, etc.)
  waiting: boolean;        // Blocked on before hook or target polling
}

Controls

All 10 methods for programmatic tour control:

type Controls = {
  close(origin?: Origin | null): void;
  // Close the current step and advance to the next one.
  // Optional origin for event tracking.

  go(nextIndex: number): void;
  // Jump to a specific step by index.
  // Uncontrolled mode only — logs warning in controlled mode.

  info(): State;
  // Get the current tour state snapshot.

  next(): void;
  // Advance to the next step.

  open(): void;
  // Open the tooltip for the current step (skip beacon).

  prev(): void;
  // Go back to the previous step.

  reset(restart?: boolean): void;
  // Reset the tour to the beginning.
  // If restart=true, also starts the tour.
  // Uncontrolled mode only — logs warning in controlled mode.

  skip(origin?: 'button_close' | 'button_skip'): void;
  // Skip (end) the tour entirely. Sets status to SKIPPED.

  start(nextIndex?: number): void;
  // Start the tour. Optionally at a specific step index.

  stop(advance?: boolean): void;
  // Stop (pause) the tour. Sets status to PAUSED.
  // If advance=true, moves to next step before stopping.
}

UseJoyrideReturn

type UseJoyrideReturn = {
  controls: Controls;
  // Programmatic tour control methods.

  failures: StepFailure[];
  // Steps that failed (target not found, before hook errors).
  // Clears on start/reset.

  on: (eventType: Events, handler: EventHandler) => () => void;
  // Subscribe to a specific event type.
  // Returns an unsubscribe function.

  state: State;
  // Current tour state (reactive, updates on changes).

  step: StepMerged | null;
  // Current merged step, or null if no step is active.

  Tour: ReactElement | null;
  // The tour React element. Render this in your JSX.
}

StepFailure

interface StepFailure {
  reason: 'before_hook' | 'target_not_found';
  step: StepMerged;
}

Placement

type Placement =
  | 'top' | 'top-start' | 'top-end'
  | 'bottom' | 'bottom-start' | 'bottom-end'
  | 'left' | 'left-start' | 'left-end'
  | 'right' | 'right-start' | 'right-end';

// Step also accepts: 'auto' (Floating UI auto-placement) and 'center' (modal-style)

Common Patterns

Async Transitions with before/after Hooks (Preferred)

The library handles waiting for async operations. Use before hooks to prepare the UI before a step shows (open dropdowns, load data, trigger animations). The tour waits for the promise to resolve. Use after hooks for cleanup (fire-and-forget, does not block).

This is the preferred approach over controlled mode for most async scenarios.

import { useState } from 'react';
import { ACTIONS, STATUS, useJoyride } from 'react-joyride';

function Dashboard() {
  const [run, setRun] = useState(false);
  const [isMenuOpen, setIsMenuOpen] = useState(false);

  const { Tour } = useJoyride({
    continuous: true,
    run,
    steps: [
      {
        target: '.nav-bar',
        content: 'This is the navigation',
        skipBeacon: true,
      },
      {
        target: '.dropdown-item', // Element inside the dropdown
        content: 'This dropdown item is important',
        skipBeacon: true,
        before: ({ action }) => {
          // Open dropdown before this step — runs on both forward and back navigation
          setIsMenuOpen(true);
          return new Promise(resolve => setTimeout(resolve, 300));
        },
      },
      {
        target: '.main-content',
        content: 'And here is the main content',
        before: ({ action }) => {
          // Close dropdown when moving to this step
          setIsMenuOpen(false);
          return new Promise(resolve => setTimeout(resolve, 300));
        },
      },
    ],
    onEvent: (data) => {
      if ([STATUS.FINISHED, STATUS.SKIPPED].includes(data.status)) {
        setRun(false);
        setIsMenuOpen(false);
      }
    },
  });

  return (
    <div>
      {Tour}
      <button onClick={() => setRun(true)}>Start Tour</button>
      {/* ... */}
    </div>
  );
}

Before/After Hooks

Async data loading before a step

{
  target: '.user-profile',
  content: 'Here is your profile data',
  before: async () => {
    await fetchUserProfile();
    // Tour waits for this promise to resolve
  },
  beforeTimeout: 10000, // Allow up to 10s
}

Analytics tracking after a step

{
  target: '.feature',
  content: 'Check out this feature',
  after: (data) => {
    // Fire-and-forget — does not block the tour
    analytics.track('tour_step_completed', {
      stepIndex: data.index,
      action: data.action,
    });
  },
}

Delayed transitions (e.g., waiting for animation)

{
  target: '.sidebar',
  content: 'The sidebar',
  before: ({ action }) => {
    // Only delay when navigating forward (not on back)
    const ms = action === ACTIONS.PREV ? 0 : 300;
    return new Promise(resolve => setTimeout(resolve, ms));
  },
}

Custom Tooltip Component

import type { TooltipRenderProps } from 'react-joyride';

function CustomTooltip({
  backProps,
  closeProps,
  index,
  isLastStep,
  primaryProps,
  size,
  skipProps,
  step,
  tooltipProps,
}: TooltipRenderProps) {
  return (
    <div
      {...tooltipProps}
      style={{
        background: '#fff',
        borderRadius: 8,
        maxWidth: 400,
        padding: 20,
        width: step.width,
      }}
    >
      {step.title && <h3 style={{ margin: '0 0 8px' }}>{step.title}</h3>}
      <div>{step.content}</div>

      <div style={{ display: 'flex', justifyContent: 'space-between', marginTop: 16 }}>
        {step.buttons.includes('skip') && !isLastStep && (
          <button {...skipProps} type="button">Skip</button>
        )}
        <div style={{ display: 'flex', gap: 8, marginLeft: 'auto' }}>
          {index > 0 && (
            <button {...backProps} type="button">Back</button>
          )}
          <button {...primaryProps} type="button">
            {isLastStep ? 'Done' : `Next (${index + 1}/${size})`}
          </button>
        </div>
      </div>
    </div>
  );
}

// Usage:
// <Joyride tooltipComponent={CustomTooltip} ... />
// or in useJoyride: useJoyride({ tooltipComponent: CustomTooltip, ... })

Event Subscription with on()

function App() {
  const { on, Tour } = useJoyride({
    steps,
    run: true,
    continuous: true,
  });

  useEffect(() => {
    const unsubs = [
      on('tour:start', (data) => {
        console.log('Tour started');
      }),
      on('tooltip', (data) => {
        analytics.track('step_viewed', { index: data.index });
      }),
      on('tour:end', (data) => {
        const wasSkipped = data.status === 'skipped';
        analytics.track('tour_ended', { skipped: wasSkipped, lastStep: data.index });
      }),
    ];

    return () => unsubs.forEach(unsub => unsub());
  }, [on]);

  return <div>{Tour}</div>;
}

Dynamic Steps

function App() {
  const [steps, setSteps] = useState<Step[]>([]);

  useEffect(() => {
    // Build steps based on feature flags, user role, etc.
    const dynamicSteps: Step[] = [
      { target: '.dashboard', content: 'Welcome to your dashboard' },
    ];

    if (user.isAdmin) {
      dynamicSteps.push({
        target: '.admin-panel',
        content: 'Admin controls are here',
      });
    }

    if (featureFlags.newSearch) {
      dynamicSteps.push({
        target: '.search-bar',
        content: 'Try the new search',
      });
    }

    setSteps(dynamicSteps);
  }, [user, featureFlags]);

  return (
    <Joyride
      run={steps.length > 0}
      steps={steps}
      continuous
    />
  );
}

React Ref Targets

function App() {
  const sidebarRef = useRef<HTMLDivElement>(null);
  const buttonRef = useRef<HTMLButtonElement>(null);

  const steps: Step[] = [
    { target: sidebarRef, content: 'Navigation sidebar' },
    { target: buttonRef, content: 'Click here to create' },
    { target: '.css-selector', content: 'Mix refs with selectors' },
  ];

  return (
    <div>
      <Joyride steps={steps} run continuous />
      <div ref={sidebarRef}>Sidebar</div>
      <button ref={buttonRef}>Create</button>
      <span className="css-selector">Other element</span>
    </div>
  );
}

Restart / Resume Tour

function App() {
  const [run, setRun] = useState(false);
  const [initialStepIndex, setInitialStepIndex] = useState(0);

  const handleStart = () => {
    setInitialStepIndex(0);
    setRun(true);
  };

  const handleResume = (fromStep: number) => {
    setInitialStepIndex(fromStep);
    setRun(true);
  };

  return (
    <div>
      <Joyride
        run={run}
        initialStepIndex={initialStepIndex}
        steps={steps}
        continuous
        onEvent={(data) => {
          if ([STATUS.FINISHED, STATUS.SKIPPED].includes(data.status)) {
            setRun(false);
          }
        }}
      />
      <button onClick={handleStart}>Start Tour</button>
      <button onClick={() => handleResume(3)}>Resume from Step 4</button>
    </div>
  );
}

Center Placement (Modal Style)

{
  target: 'body',
  placement: 'center',
  content: (
    <div>
      <h2>Welcome!</h2>
      <p>This appears as a centered modal overlay.</p>
    </div>
  ),
  // Center placement automatically hides beacon and arrow
}