React Joyride

Joyride operates as a state machine with several statuses. Understanding these transitions helps you manage the tour's lifecycle programmatically.

Tour Statuses

• idle: Initial state. No tour running.
• waiting: Tour started but no steps are loaded yet. Transitions to running once steps are available.
• ready: Steps are loaded, tour is ready to start.
• running: Tour is active and displaying steps.
• paused: Tour was stopped mid-way via controls.stop(). Can be resumed.
• finished: All steps completed.
• skipped: User clicked Skip to exit early.

Key Transitions

• Starting: Setting run={true} or calling controls.start() moves the tour to running (or waiting if steps aren't loaded). Calling controls.start() from a paused state resumes the tour.
• Stopping: Setting run={false} or calling controls.stop() moves the tour to paused. Using the Skip button or controls.skip() moves it to skipped. Completing the last step or clicking Close on the final step moves it to finished.
• Resetting: controls.reset() moves the tour to ready. controls.reset(true) restarts the tour immediately in the running state.

To customize the appearance of the tour tooltips, provide a component to the tooltipComponent prop in Joyride or the useJoyride hook. The component receives TooltipRenderProps which includes access to the current step, navigation props (backProps, closeProps, primaryProps, skipProps), and metadata (index, isLastStep, size).

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, ... })

Controlled mode is used when an external system must own the stepIndex (e.g., a persistence layer that resumes a tour on reload, or a parent orchestrator).

Warning: Do not use controlled mode just for conditional UI (like opening a sidebar). Instead, use the before step hook. Driving stepIndex via useEffect can desynchronize the lifecycle and break overlay/keyboard handlers.

To implement controlled mode, you must manage the stepIndex yourself and update it within the onEvent callback.

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

<Joyride
  continuous
  run={run}
  stepIndex={stepIndex}
  steps={steps}
  onEvent={(data, controls) => {
    const { action, index, status, type } = data;

    if ([EVENTS.STEP_AFTER, EVENTS.TARGET_NOT_FOUND].includes(type)) {
      setStepIndex(index + (action === ACTIONS.PREV ? -1 : 1));
    } else if ([STATUS.FINISHED, STATUS.SKIPPED].includes(status)) {
      setRun(false);
    }
  }}
/>

Uncontrolled Mode (Recommended)

By default, the tour manages its own navigation. Use before and after hooks to handle asynchronous UI changes (like opening a dropdown or waiting for an animation). The library automatically waits for the before promise to resolve.

Controlled Mode

Use this sparingly when you must sync the stepIndex with external state (e.g., URL parameters).

Rules for Controlled Mode:

• go() and reset() are disabled.
• You must manually update stepIndex in response to events (like step:after).
• The tour pauses at COMPLETE; you must manually advance it.
• You must provide the stepIndex prop to useJoyride or <Joyride>.

// Controlled Mode Example
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));
    }
  },
});