React JoyrideSAFE

Create guided tours in your apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: react-joyride
description: >-
  Guide for implementing, configuring, and debugging React Joyride v3 guided tours.
  Use this skill whenever the user mentions joyride, guided tour, onboarding tour,
  walkthrough, tooltip tour, step-by-step guide, product tour, or wants to highlight
  UI elements sequentially. Also use when debugging tour issues like tooltips not
  appearing, targets not found, or controlled mode problems. This skill covers the
  useJoyride hook, Joyride component, step configuration, events, controls, custom
  components, and styling.
license: MIT
metadata:
  author: gilbarbara
  version: "3.0.0"
---

# 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)

```tsx
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

```tsx
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.

```tsx
{
  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

```tsx
// 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)

| Option | Default | Description |
|--------|---------|-------------|
| `placement` | `'bottom'` | Tooltip position. Use `'center'` for modal-style (requires `target: 'body'`) |
| `skipBeacon` | `false` | Skip beacon, show tooltip directly |
| `buttons` | `['back','close','primary']` | Buttons in tooltip. Add `'skip'` for skip button |
| `hideOverlay` | `false` | Don't show dark overlay |
| `blockTargetInteraction` | `false` | Block clicks on highlighted element |
| `before` | - | `(data) => Promise<void>` — async hook before step shows |
| `after` | - | `(data) => void` — fire-and-forget hook after step completes |
| `skipScroll` | `false` | Don't scroll to target |
| `scrollTarget` | - | Scroll to this element instead of `target` |
| `spotlightTarget` | - | Highlight this element instead of `target` |
| `spotlightPadding` | `10` | Padding around spotlight. Number or `{ top, right, bottom, left }` |
| `targetWaitTimeout` | `1000` | ms to wait for target to appear. `0` = no waiting |
| `beforeTimeout` | `5000` | ms to wait for `before` hook. `0` = no timeout |

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.

```tsx
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 aft

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: React Joyride](https://modelsatlas.com/skills/gilbarbara/react-joyride/badge.svg)](https://modelsatlas.com/skills/gilbarbara/react-joyride/)

Not your listing, or something out of date? Claim or update your listing.