Skip to main content
ZICQ

Skills ZICQ category:Agent Workflows react-joyride

React Joyride

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.

619 installs

Official URL:skills.sh

What this skill does

Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.

What it does

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.

When to use it

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

How agents load it

Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: React Joyride v3; Quick Start; Using the hook (recommended); Using the component; Core Concepts; Step Configuration. It includes spec-recommended sections: step-by-step instructions.

File analysis

File analysis: besides SKILL.md, the body references references/api-props-options.md, references/api-step-state-controls.md, references/api-events-components.md, references/patterns.md. Those resources load on demand.

React Joyride v3Quick StartUsing the hook (recommended)Using the componentCore ConceptsStep ConfigurationTarget typesCommon step options (override per-step)Uncontrolled vs ControlledUncontrolled (default — strongly preferred)Controlled (with `stepIndex`) — use sparinglyEvent System

· License:MIT

Source category:skills.sh agent-skill

SKILL.md & Agent activation

Official spec ↗
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
  1. DiscoverThe client exposes names and descriptions to the agent.
  2. ActivateYour request or the task context selects the skill and loads its instructions.
  3. Load resourcesReferenced scripts, documentation and assets are used when needed.
Files referenced by the instructions · 4
  • references/api-props-options.md
  • references/api-step-state-controls.md
  • references/api-events-components.md
  • references/patterns.md

These paths are extracted from the text. Check the upstream package to verify the files exist.

Invocation syntax and available tools depend on your Agent client. Client integration guide ↗

Install this skill

Skills CLI ↗

Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.

This skill references supporting files. Retrieve the complete directory from the source; copying SKILL.md alone may leave missing dependencies.

Ask your Agent to install

Copy these instructions to a compatible agent and confirm the target directory matches your client.

Install the agent skill "react-joyride" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-0548be28d3362d12-React-Joyride.html
Save it as .cursor/skills/react-joyride/SKILL.md or .claude/skills/react-joyride/SKILL.md and keep the frontmatter name and description exactly as-is.
This skill also ships scripts/, references/, or assets/ — fetch the whole folder from https://github.com/gilbarbara/react-joyride instead of creating only a SKILL.md.

Full package on GitHub ↗

Install from the terminal · Skills CLI

Requires Node.js and npx. First inspect the repository's skill list to confirm the name.

npx skills add 'https://github.com/gilbarbara/react-joyride' --list

npx skills add 'https://github.com/gilbarbara/react-joyride' --skill 'react-joyride'

The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.

Readable layout
--- 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 `` 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
{Tour}{/* rest of app */}
; } ``` ### Using the component ```tsx import { Joyride, STATUS, Status } from 'react-joyride'; function App() { return ( { 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` — 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 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). ```tsx 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 ```tsx 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 | When | |-------|------| | `tour:start` | Tour begins | | `step:before_hook` | `before` hook is called | | `step:before` | Target found, step about to render | | `scroll:start` | Scrolling to target | | `scroll:end` | Scroll complete | | `beacon` | Beacon shown | | `tooltip` | Tooltip shown | | `step:after` | User navigated (next/prev/close/skip) | | `step:after_hook` | `after` hook called | | `tour:end` | Tour finished or skipped | | `tour:status` | Status changed (on stop/reset) | | `error:target_not_found` | Target element not found | | `error` | Generic error | ### Event subscription with `on()` ```tsx 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: | Method | Description | |--------|-------------| | `next()` | Advance to next step | | `prev()` | Go to previous step | | `close(origin?)` | Close current step, advance | | `skip(origin?)` | Skip the tour entirely | | `start(index?)` | Start the tour | | `stop(advance?)` | Stop (pause) the tour | | `go(index)` | Jump to step (uncontrolled only) | | `reset(restart?)` | Reset tour (uncontrolled only) | | `open()` | Open tooltip for current step | | `info()` | Get current state | Docs: https://v3.react-joyride.com/docs/hook ## Styling & Theming Three layers of customization (from simple to full control): ### 1. Color options (simplest) ```tsx 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 ```tsx 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 ```tsx import type { TooltipRenderProps } from 'react-joyride'; function MyTooltip({ backProps, index, primaryProps, size, skipProps, step, tooltipProps }: TooltipRenderProps) { return (
{step.title &&

{step.title}

}
{step.content}
{index > 0 && Back} Next
); } // Usage ``` **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 `` (placed inside a `` 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 | I need to... | Use | |---|---| | Wait for async UI changes between steps (dropdown, animation, data load) | `before` hook returning a Promise — not controlled mode | | Control step navigation externally (URL sync, external state machine) | Controlled mode with `stepIndex` — but try `before`/`after` hooks first | | Track which steps failed (target missing, hook error) | `failures` array from `useJoyride()` return | | Listen to specific events without `onEvent` switch | `on('event:type', handler)` from `useJoyride()` return | | Show a centered modal-style step | `target: 'body'` + `placement: 'center'` | ## 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. ```tsx // 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 `` 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 ```tsx // 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

Related skills

Agent Workflows

Skill Creator

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that exte…

Agent Workflows

Clawdhub

Use the ClawdHub CLI to search, install, update, and publish agent skills from clawdhub.com. Use when you need to fetch new skills on the fl…

Agent Workflows

Agent Team Orchestration

Orchestrate multi-agent teams with defined roles, task lifecycles, handoff protocols, and review workflows. Use when: (1) Setting up a team …

Agent Workflows

Superpowers

Spec-first, TDD, subagent-driven software development workflow. Use when: (1) building any new feature or app — triggers brainstorm → plan →…