{"owner":"gilbarbara","repo":"react-joyride","hasSkills":true,"totalSkillsCount":7,"totalTokensCount":16955,"categories":["anthropic-skill","claude-rule","project-spec"],"hasMcp":false,"mcpConfig":null,"found":["skills/react-joyride/references/api-step-state-controls.md","skills/react-joyride/references/api-events-components.md","CLAUDE.md","docs/architecture.md","skills/react-joyride/references/api-props-options.md","skills/react-joyride/references/patterns.md","skills/react-joyride/SKILL.md"],"skills":{"skills/react-joyride/references/api-step-state-controls.md":"# Step, State, Controls\n\n## Step\n\nA single step provided by the user. Extends `SharedProps` and `Partial`.\n\n```typescript\ntype Step = SharedProps & Partial & {\n // Required\n content: ReactNode; // Tooltip body\n target: StepTarget; // Element to highlight\n\n // Optional\n id?: string; // Unique identifier\n title?: ReactNode; // Tooltip title\n data?: any; // Custom data (passed to callbacks)\n\n // Positioning\n placement?: Placement | 'auto' | 'center'; // Default: 'bottom'\n beaconPlacement?: Placement; // Beacon-specific placement\n isFixed?: boolean; // Force fixed positioning (default: false)\n\n // Alternate targets\n scrollTarget?: StepTarget; // Scroll to this instead of target\n spotlightTarget?: StepTarget; // Highlight this instead of target\n}\n```\n\nAll `Options` fields (see api-props-options.md) are also valid on Step for per-step overrides.\n\n## StepTarget\n\nFour ways to specify a target element:\n\n```typescript\ntype StepTarget =\n | string // CSS selector\n | HTMLElement // Direct element reference\n | RefObject // React ref\n | (() => HTMLElement | null); // Function (re-evaluated each lifecycle)\n```\n\n## StepMerged\n\nThe normalized step after defaults are applied. All `Options` fields become required, plus:\n- `spotlightPadding: Required` (always `{ top, right, bottom, left }`)\n- `styles: Styles` (fully resolved)\n\nThis is what you receive in event callbacks and custom component props.\n\n## State\n\n```typescript\ntype State = {\n action: Actions; // What triggered the update (init, start, next, prev, etc.)\n controlled: boolean; // true when stepIndex prop is set\n index: number; // Current step index\n lifecycle: Lifecycle; // Step rendering phase\n origin: Origin | null; // UI element that triggered action\n scrolling: boolean; // Scroll animation in progress\n size: number; // Total number of steps\n status: Status; // Tour status (idle, ready, running, etc.)\n waiting: boolean; // Blocked on before hook or target polling\n}\n```\n\n## Controls\n\nAll 10 methods for programmatic tour control:\n\n```typescript\ntype Controls = {\n close(origin?: Origin | null): void;\n // Close the current step and advance to the next one.\n // Optional origin for event tracking.\n\n go(nextIndex: number): void;\n // Jump to a specific step by index.\n // Uncontrolled mode only — logs warning in controlled mode.\n\n info(): State;\n // Get the current tour state snapshot.\n\n next(): void;\n // Advance to the next step.\n\n open(): void;\n // Open the tooltip for the current step (skip beacon).\n\n prev(): void;\n // Go back to the previous step.\n\n reset(restart?: boolean): void;\n // Reset the tour to the beginning.\n // If restart=true, also starts the tour.\n // Uncontrolled mode only — logs warning in controlled mode.\n\n skip(origin?: 'button_close' | 'button_skip'): void;\n // Skip (end) the tour entirely. Sets status to SKIPPED.\n\n start(nextIndex?: number): void;\n // Start the tour. Optionally at a specific step index.\n\n stop(advance?: boolean): void;\n // Stop (pause) the tour. Sets status to PAUSED.\n // If advance=true, moves to next step before stopping.\n}\n```\n\n## UseJoyrideReturn\n\n```typescript\ntype UseJoyrideReturn = {\n controls: Controls;\n // Programmatic tour control methods.\n\n failures: StepFailure[];\n // Steps that failed (target not found, before hook errors).\n // Clears on start/reset.\n\n on: (eventType: Events, handler: EventHandler) => () => void;\n // Subscribe to a specific event type.\n // Returns an unsubscribe function.\n\n state: State;\n // Current tour state (reactive, updates on changes).\n\n step: StepMerged | null;\n // Current merged step, or null if no step is active.\n\n Tour: ReactElement | null;\n // The tour React element. Render this in your JSX.\n}\n```\n\n## StepFailure\n\n```typescript\ninterface StepFailure {\n reason: 'before_hook' | 'target_not_found';\n step: StepMerged;\n}\n```\n\n## Placement\n\n```typescript\ntype Placement =\n | 'top' | 'top-start' | 'top-end'\n | 'bottom' | 'bottom-start' | 'bottom-end'\n | 'left' | 'left-start' | 'left-end'\n | 'right' | 'right-start' | 'right-end';\n\n// Step also accepts: 'auto' (Floating UI auto-placement) and 'center' (modal-style)\n```\n","skills/react-joyride/references/api-events-components.md":"# Events, Constants, Custom Components\n\n## Constants\n\n### ACTIONS\n```typescript\nconst ACTIONS = {\n INIT: 'init',\n START: 'start',\n STOP: 'stop',\n RESET: 'reset',\n PREV: 'prev',\n NEXT: 'next',\n GO: 'go',\n CLOSE: 'close',\n SKIP: 'skip',\n UPDATE: 'update',\n COMPLETE: 'complete',\n} as const;\n```\n\n### EVENTS\n```typescript\nconst EVENTS = {\n TOUR_START: 'tour:start',\n STEP_BEFORE_HOOK: 'step:before_hook',\n STEP_BEFORE: 'step:before',\n SCROLL_START: 'scroll:start',\n SCROLL_END: 'scroll:end',\n BEACON: 'beacon',\n TOOLTIP: 'tooltip',\n STEP_AFTER: 'step:after',\n STEP_AFTER_HOOK: 'step:after_hook',\n TOUR_END: 'tour:end',\n TOUR_STATUS: 'tour:status',\n TARGET_NOT_FOUND: 'error:target_not_found',\n ERROR: 'error',\n} as const;\n```\n\n### LIFECYCLE\n```typescript\nconst LIFECYCLE = {\n INIT: 'init',\n READY: 'ready',\n BEACON_BEFORE: 'beacon_before',\n BEACON: 'beacon',\n TOOLTIP_BEFORE: 'tooltip_before',\n TOOLTIP: 'tooltip',\n COMPLETE: 'complete',\n} as const;\n```\n\n### STATUS\n```typescript\nconst STATUS = {\n IDLE: 'idle',\n READY: 'ready',\n WAITING: 'waiting',\n RUNNING: 'running',\n PAUSED: 'paused',\n SKIPPED: 'skipped',\n FINISHED: 'finished',\n} as const;\n```\n\n### ORIGIN\n```typescript\nconst ORIGIN = {\n BUTTON_CLOSE: 'button_close',\n BUTTON_SKIP: 'button_skip',\n BUTTON_PRIMARY: 'button_primary',\n KEYBOARD: 'keyboard',\n OVERLAY: 'overlay',\n} as const;\n```\n\n## Event Types\n\n### EventData\n\nThe full payload passed to `onEvent` and event subscribers:\n\n```typescript\ntype EventData = TourData & {\n error: Error | null; // Only for 'error' events\n scroll: ScrollData | null; // Only for 'scroll:start' / 'scroll:end'\n scrolling: boolean;\n type: Events; // The event type (discriminator)\n waiting: boolean;\n}\n```\n\n### TourData\n\nBase payload (also passed to `before` and `after` hooks):\n\n```typescript\ninterface TourData {\n action: Actions;\n controlled: boolean;\n index: number;\n lifecycle: Lifecycle;\n origin: Origin | null;\n size: number;\n status: Status;\n step: StepMerged;\n}\n```\n\n### EventHandler\n\n```typescript\ntype EventHandler = (data: EventData, controls: Controls) => void;\n```\n\n### ScrollData\n\n```typescript\ntype ScrollData = {\n duration: number; // Scroll duration in ms\n element: Element; // Element being scrolled\n initial: number; // Scroll position before\n target: number; // Computed scroll destination\n}\n```\n\n## Event Flow (per step)\n\n```\ntour:start (once)\n |\n v\nstep:before_hook (if before hook exists)\n |\n v\nstep:before (target found, step about to render)\n |\n v\nscroll:start / scroll:end (if scrolling needed)\n |\n v\nbeacon (if beacon shown) OR tooltip (if beacon skipped)\n |\n v (user clicks beacon)\ntooltip\n |\n v (user clicks next/prev/close/skip)\nstep:after\n |\n v\nstep:after_hook (if after hook exists)\n |\n v (next step or tour end)\ntour:end (when finished/skipped)\n```\n\n## Custom Component Render Props\n\n### TooltipRenderProps\n\n```typescript\ntype TooltipRenderProps = {\n // Tour state\n continuous: boolean;\n index: number;\n isLastStep: boolean;\n size: number;\n step: StepMerged;\n\n // Button props (spread on button elements)\n backProps: {\n 'aria-label': string;\n 'data-action': string;\n onClick: MouseEventHandler;\n role: string;\n title: string;\n };\n closeProps: { /* same shape */ };\n primaryProps: { /* same shape */ };\n skipProps: { /* same shape */ };\n\n // Container props (spread on tooltip wrapper)\n tooltipProps: {\n 'aria-modal': boolean;\n role: string; // 'dialog'\n };\n\n // Tour controls\n controls: Controls;\n}\n```\n\n**Important**: Always spread `tooltipProps` on the root element and button props on their respective buttons. This ensures correct accessibility attributes and action handling.\n\n### BeaconRenderProps\n\n```typescript\ntype BeaconRenderProps = {\n continuous: boolean;\n index: number;\n isLastStep: boolean;\n size: number;\n step: StepMerged;\n}\n```\n\nMust render a `` since it's placed inside a `\n {/* ... */}\n \n );\n}\n```\n\n## Before/After Hooks\n\n### Async data loading before a step\n\n```tsx\n{\n target: '.user-profile',\n content: 'Here is your profile data',\n before: async () => {\n await fetchUserProfile();\n // Tour waits for this promise to resolve\n },\n beforeTimeout: 10000, // Allow up to 10s\n}\n```\n\n### Analytics tracking after a step\n\n```tsx\n{\n target: '.feature',\n content: 'Check out this feature',\n after: (data) => {\n // Fire-and-forget — does not block the tour\n analytics.track('tour_step_completed', {\n stepIndex: data.index,\n action: data.action,\n });\n },\n}\n```\n\n### Delayed transitions (e.g., waiting for animation)\n\n```tsx\n{\n target: '.sidebar',\n content: 'The sidebar',\n before: ({ action }) => {\n // Only delay when navigating forward (not on back)\n const ms = action === ACTIONS.PREV ? 0 : 300;\n return new Promise(resolve => setTimeout(resolve, ms));\n },\n}\n```\n\n## Custom Tooltip Component\n\n```tsx\nimport type { TooltipRenderProps } from 'react-joyride';\n\nfunction CustomTooltip({\n backProps,\n closeProps,\n index,\n isLastStep,\n primaryProps,\n size,\n skipProps,\n step,\n tooltipProps,\n}: TooltipRenderProps) {\n return (\n \n {step.title &&

{step.title}

}\n
{step.content}
\n\n
\n {step.buttons.includes('skip') && !isLastStep && (\n \n )}\n
\n {index > 0 && (\n \n )}\n \n
\n
\n \n );\n}\n\n// Usage:\n// \n// or in useJoyride: useJoyride({ tooltipComponent: CustomTooltip, ... })\n```\n\n## Event Subscription with `on()`\n\n```tsx\nfunction App() {\n const { on, Tour } = useJoyride({\n steps,\n run: true,\n continuous: true,\n });\n\n useEffect(() => {\n const unsubs = [\n on('tour:start', (data) => {\n console.log('Tour started');\n }),\n on('tooltip', (data) => {\n analytics.track('step_viewed', { index: data.index });\n }),\n on('tour:end', (data) => {\n const wasSkipped = data.status === 'skipped';\n analytics.track('tour_ended', { skipped: wasSkipped, lastStep: data.index });\n }),\n ];\n\n return () => unsubs.forEach(unsub => unsub());\n }, [on]);\n\n return
{Tour}
;\n}\n```\n\n## Dynamic Steps\n\n```tsx\nfunction App() {\n const [steps, setSteps] = useState([]);\n\n useEffect(() => {\n // Build steps based on feature flags, user role, etc.\n const dynamicSteps: Step[] = [\n { target: '.dashboard', content: 'Welcome to your dashboard' },\n ];\n\n if (user.isAdmin) {\n dynamicSteps.push({\n target: '.admin-panel',\n content: 'Admin controls are here',\n });\n }\n\n if (featureFlags.newSearch) {\n dynamicSteps.push({\n target: '.search-bar',\n content: 'Try the new search',\n });\n }\n\n setSteps(dynamicSteps);\n }, [user, featureFlags]);\n\n return (\n 0}\n steps={steps}\n continuous\n />\n );\n}\n```\n\n## React Ref Targets\n\n```tsx\nfunction App() {\n const sidebarRef = useRef(null);\n const buttonRef = useRef(null);\n\n const steps: Step[] = [\n { target: sidebarRef, content: 'Navigation sidebar' },\n { target: buttonRef, content: 'Click here to create' },\n { target: '.css-selector', content: 'Mix refs with selectors' },\n ];\n\n return (\n
\n \n
Sidebar
\n \n Other element\n
\n );\n}\n```\n\n## Restart / Resume Tour\n\n```tsx\nfunction App() {\n const [run, setRun] = useState(false);\n const [initialStepIndex, setInitialStepIndex] = useState(0);\n\n const handleStart = () => {\n setInitialStepIndex(0);\n setRun(true);\n };\n\n const handleResume = (fromStep: number) => {\n setInitialStepIndex(fromStep);\n setRun(true);\n };\n\n return (\n
\n {\n if ([STATUS.FINISHED, STATUS.SKIPPED].includes(data.status)) {\n setRun(false);\n }\n }}\n />\n \n \n
\n );\n}\n```\n\n## Center Placement (Modal Style)\n\n```tsx\n{\n target: 'body',\n placement: 'center',\n content: (\n
\n

Welcome!

\n

This appears as a centered modal overlay.

\n
\n ),\n // Center placement automatically hides beacon and arrow\n}\n```\n","skills/react-joyride/SKILL.md":"---\nname: react-joyride\ndescription: >-\n Guide for implementing, configuring, and debugging React Joyride v3 guided tours.\n Use this skill whenever the user mentions joyride, guided tour, onboarding tour,\n walkthrough, tooltip tour, step-by-step guide, product tour, or wants to highlight\n UI elements sequentially. Also use when debugging tour issues like tooltips not\n appearing, targets not found, or controlled mode problems. This skill covers the\n useJoyride hook, Joyride component, step configuration, events, controls, custom\n components, and styling.\nlicense: MIT\nmetadata:\n author: gilbarbara\n version: \"3.0.0\"\n---\n\n# React Joyride v3\n\nCreate guided tours in React apps. Two public APIs: the `useJoyride()` hook (recommended) and the `` component.\n\nOnline docs: https://v3.react-joyride.com\n\n## Quick Start\n\n### Using the hook (recommended)\n\n```tsx\nimport { useJoyride, STATUS, Status } from 'react-joyride';\n\nfunction App() {\n const { Tour } = useJoyride({\n continuous: true,\n run: true,\n steps: [\n { target: '.my-element', content: 'This is the first step', title: 'Welcome' },\n { target: '#sidebar', content: 'Navigate here', placement: 'right' },\n ],\n onEvent: (data) => {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n // Tour ended\n }\n },\n });\n\n return
{Tour}{/* rest of app */}
;\n}\n```\n\n### Using the component\n\n```tsx\nimport { Joyride, STATUS, Status } from 'react-joyride';\n\nfunction App() {\n return (\n {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n // Tour ended\n }\n }}\n />\n );\n}\n```\n\nThe hook returns `{ controls, failures, on, state, step, Tour }`. Render `Tour` in your JSX.\n\nDocs: https://v3.react-joyride.com/docs/getting-started\n\n## Core Concepts\n\nThe tour has two state dimensions:\n\n**Tour Status**: `idle -> ready -> waiting -> running <-> paused -> finished | skipped`\n- `idle`: No steps loaded\n- `ready`: Steps loaded, waiting for `run: true`\n- `waiting`: `run=true` but steps loading async (transitions to running when steps arrive)\n- `running`: Tour active\n- `paused`: Tour paused (controlled mode at COMPLETE, or `stop()` called)\n- `finished` / `skipped`: Tour ended\n\n**Step Lifecycle** (per step): `init -> ready -> beacon_before -> beacon -> tooltip_before -> tooltip -> complete`\n- `*_before` phases: scrolling and positioning happen here\n- `beacon`: Pulsing indicator shown (skipped when `continuous` + navigating, `skipBeacon`, or `placement: 'center'`)\n- `tooltip`: The tooltip is visible and interactive\n\nDocs: https://v3.react-joyride.com/docs/how-it-works\n\n## Step Configuration\n\nEach step requires `target` and `content`. All other fields are optional.\n\n```tsx\n{\n target: '.my-element', // CSS selector, HTMLElement, React ref, or () => HTMLElement\n content: 'Step body text', // ReactNode\n title: 'Optional title', // ReactNode\n placement: 'bottom', // Default. Also: top, left, right, *-start, *-end, auto, center\n id: 'unique-id', // Optional identifier\n data: { custom: 'data' }, // Attached to event callbacks\n}\n```\n\n### Target types\n\n```tsx\n// CSS selector\n{ target: '.sidebar-nav' }\n// HTMLElement\n{ target: document.getElementById('my-el') }\n// React ref\nconst ref = useRef(null);\n{ target: ref }\n// Function (evaluated each lifecycle)\n{ target: () => document.querySelector('.dynamic-element') }\n```\n\n### Common step options (override per-step)\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `placement` | `'bottom'` | Tooltip position. Use `'center'` for modal-style (requires `target: 'body'`) |\n| `skipBeacon` | `false` | Skip beacon, show tooltip directly |\n| `buttons` | `['back','close','primary']` | Buttons in tooltip. Add `'skip'` for skip button |\n| `hideOverlay` | `false` | Don't show dark overlay |\n| `blockTargetInteraction` | `false` | Block clicks on highlighted element |\n| `before` | - | `(data) => Promise` — async hook before step shows |\n| `after` | - | `(data) => void` — fire-and-forget hook after step completes |\n| `skipScroll` | `false` | Don't scroll to target |\n| `scrollTarget` | - | Scroll to this element instead of `target` |\n| `spotlightTarget` | - | Highlight this element instead of `target` |\n| `spotlightPadding` | `10` | Padding around spotlight. Number or `{ top, right, bottom, left }` |\n| `targetWaitTimeout` | `1000` | ms to wait for target to appear. `0` = no waiting |\n| `beforeTimeout` | `5000` | ms to wait for `before` hook. `0` = no timeout |\n\nAll `Options` fields can be set globally via `options` prop or per-step. Per-step values override global.\n\nDocs: https://v3.react-joyride.com/docs/step | https://v3.react-joyride.com/docs/props/options\n\n## Uncontrolled vs Controlled\n\n### Uncontrolled (default — strongly preferred)\n\nThe tour manages step navigation internally. This is the right choice for most use cases.\n\n**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.\n\n```tsx\nconst { Tour } = useJoyride({\n continuous: true,\n run: isRunning,\n steps: [\n { target: '.nav', content: 'Navigation' },\n {\n target: '.dropdown-item',\n content: 'Inside the dropdown',\n before: () => {\n // Open dropdown and wait for animation — tour waits automatically\n openDropdown();\n return new Promise(resolve => setTimeout(resolve, 300));\n },\n after: () => closeDropdown(), // Clean up after step (fire-and-forget)\n },\n { target: '.main-content', content: 'Main content' },\n ],\n onEvent: (data) => {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n setIsRunning(false);\n }\n },\n});\n```\n\n### Controlled (with `stepIndex`) — use sparingly\n\nOnly 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).\n\n```tsx\nconst [stepIndex, setStepIndex] = useState(0);\nconst [run, setRun] = useState(true);\n\nconst { Tour } = useJoyride({\n continuous: true,\n run,\n stepIndex, // This makes it controlled\n steps,\n onEvent: (data) => {\n const { action, index, status, type } = data;\n\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(status)) {\n setRun(false);\n return;\n }\n\n if (type === 'step:after' || type === 'error:target_not_found') {\n setStepIndex(index + (action === 'prev' ? -1 : 1));\n }\n },\n});\n```\n\n**Controlled mode rules:**\n- `go()` and `reset()` are disabled (logged warning)\n- You must update `stepIndex` in response to events\n- The tour pauses at COMPLETE — you must advance it\n- Prefer uncontrolled mode with `before`/`after` hooks unless you have a strong reason for external index management\n\n## Event System\n\n### `onEvent` callback\n\n```tsx\nonEvent: (data: EventData, controls: Controls) => void\n```\n\nThe `data` object contains the full tour state plus event-specific fields. The `controls` object lets you programmatically control the tour.\n\n### Event types (in order per step)\n\n| Event | When |\n|-------|------|\n| `tour:start` | Tour begins |\n| `step:before_hook` | `before` hook is called |\n| `step:before` | Target found, step about to render |\n| `scroll:start` | Scrolling to target |\n| `scroll:end` | Scroll complete |\n| `beacon` | Beacon shown |\n| `tooltip` | Tooltip shown |\n| `step:after` | User navigated (next/prev/close/skip) |\n| `step:after_hook` | `after` hook called |\n| `tour:end` | Tour finished or skipped |\n| `tour:status` | Status changed (on stop/reset) |\n| `error:target_not_found` | Target element not found |\n| `error` | Generic error |\n\n### Event subscription with `on()`\n\n```tsx\nconst { on, Tour } = useJoyride({ ... });\n\nuseEffect(() => {\n const unsubscribe = on('tooltip', (data, controls) => {\n analytics.track('tour_step_viewed', { step: data.index });\n });\n return unsubscribe;\n}, [on]);\n```\n\nDocs: https://v3.react-joyride.com/docs/events\n\n## Controls\n\nAvailable via `useJoyride()` return value or `onEvent` second argument:\n\n| Method | Description |\n|--------|-------------|\n| `next()` | Advance to next step |\n| `prev()` | Go to previous step |\n| `close(origin?)` | Close current step, advance |\n| `skip(origin?)` | Skip the tour entirely |\n| `start(index?)` | Start the tour |\n| `stop(advance?)` | Stop (pause) the tour |\n| `go(index)` | Jump to step (uncontrolled only) |\n| `reset(restart?)` | Reset tour (uncontrolled only) |\n| `open()` | Open tooltip for current step |\n| `info()` | Get current state |\n\nDocs: https://v3.react-joyride.com/docs/hook\n\n## Styling & Theming\n\nThree layers of customization (from simple to full control):\n\n### 1. Color options (simplest)\n\n```tsx\noptions: {\n primaryColor: '#1976d2', // Buttons and beacon\n backgroundColor: '#1a1a2e', // Tooltip background\n textColor: '#ffffff', // Tooltip text\n overlayColor: 'rgba(0,0,0,0.7)', // Overlay backdrop\n arrowColor: '#1a1a2e', // Arrow (match background)\n}\n```\n\n### 2. Styles override\n\n```tsx\nstyles: {\n tooltip: { borderRadius: 12 },\n buttonPrimary: { backgroundColor: '#1976d2' },\n buttonBack: { color: '#666' },\n spotlight: { borderRadius: 8 },\n}\n```\n\nStyle keys: `arrow`, `beacon`, `beaconInner`, `beaconOuter`, `beaconWrapper`, `buttonBack`, `buttonClose`, `buttonPrimary`, `buttonSkip`, `floater`, `loader`, `overlay`, `tooltip`, `tooltipContainer`, `tooltipContent`, `tooltipFooter`, `tooltipFooterSpacer`, `tooltipTitle`\n\n### 3. Custom components (full control)\n\nSee next section.\n\nDocs: https://v3.react-joyride.com/docs/props/styles\n\n## Custom Components\n\nReplace any UI component via props. Each receives render props with step data and button handlers.\n\n### Custom Tooltip\n\n```tsx\nimport type { TooltipRenderProps } from 'react-joyride';\n\nfunction MyTooltip({ backProps, index, primaryProps, size, skipProps, step, tooltipProps }: TooltipRenderProps) {\n return (\n
\n {step.title &&

{step.title}

}\n
{step.content}
\n
\n {index > 0 && }\n \n
\n
\n );\n}\n\n// Usage\n\n```\n\n**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.\n\n### Custom Beacon\n\nMust render a `` (placed inside a `\n {/* ... */}\n \n );\n}\n```\n\n## Before/After Hooks\n\n### Async data loading before a step\n\n```tsx\n{\n target: '.user-profile',\n content: 'Here is your profile data',\n before: async () => {\n await fetchUserProfile();\n // Tour waits for this promise to resolve\n },\n beforeTimeout: 10000, // Allow up to 10s\n}\n```\n\n### Analytics tracking after a step\n\n```tsx\n{\n target: '.feature',\n content: 'Check out this feature',\n after: (data) => {\n // Fire-and-forget — does not block the tour\n analytics.track('tour_step_completed', {\n stepIndex: data.index,\n action: data.action,\n });\n },\n}\n```\n\n### Delayed transitions (e.g., waiting for animation)\n\n```tsx\n{\n target: '.sidebar',\n content: 'The sidebar',\n before: ({ action }) => {\n // Only delay when navigating forward (not on back)\n const ms = action === ACTIONS.PREV ? 0 : 300;\n return new Promise(resolve => setTimeout(resolve, ms));\n },\n}\n```\n\n## Custom Tooltip Component\n\n```tsx\nimport type { TooltipRenderProps } from 'react-joyride';\n\nfunction CustomTooltip({\n backProps,\n closeProps,\n index,\n isLastStep,\n primaryProps,\n size,\n skipProps,\n step,\n tooltipProps,\n}: TooltipRenderProps) {\n return (\n \n {step.title &&

{step.title}

}\n
{step.content}
\n\n
\n {step.buttons.includes('skip') && !isLastStep && (\n \n )}\n
\n {index > 0 && (\n \n )}\n \n
\n
\n \n );\n}\n\n// Usage:\n// \n// or in useJoyride: useJoyride({ tooltipComponent: CustomTooltip, ... })\n```\n\n## Event Subscription with `on()`\n\n```tsx\nfunction App() {\n const { on, Tour } = useJoyride({\n steps,\n run: true,\n continuous: true,\n });\n\n useEffect(() => {\n const unsubs = [\n on('tour:start', (data) => {\n console.log('Tour started');\n }),\n on('tooltip', (data) => {\n analytics.track('step_viewed', { index: data.index });\n }),\n on('tour:end', (data) => {\n const wasSkipped = data.status === 'skipped';\n analytics.track('tour_ended', { skipped: wasSkipped, lastStep: data.index });\n }),\n ];\n\n return () => unsubs.forEach(unsub => unsub());\n }, [on]);\n\n return
{Tour}
;\n}\n```\n\n## Dynamic Steps\n\n```tsx\nfunction App() {\n const [steps, setSteps] = useState([]);\n\n useEffect(() => {\n // Build steps based on feature flags, user role, etc.\n const dynamicSteps: Step[] = [\n { target: '.dashboard', content: 'Welcome to your dashboard' },\n ];\n\n if (user.isAdmin) {\n dynamicSteps.push({\n target: '.admin-panel',\n content: 'Admin controls are here',\n });\n }\n\n if (featureFlags.newSearch) {\n dynamicSteps.push({\n target: '.search-bar',\n content: 'Try the new search',\n });\n }\n\n setSteps(dynamicSteps);\n }, [user, featureFlags]);\n\n return (\n 0}\n steps={steps}\n continuous\n />\n );\n}\n```\n\n## React Ref Targets\n\n```tsx\nfunction App() {\n const sidebarRef = useRef(null);\n const buttonRef = useRef(null);\n\n const steps: Step[] = [\n { target: sidebarRef, content: 'Navigation sidebar' },\n { target: buttonRef, content: 'Click here to create' },\n { target: '.css-selector', content: 'Mix refs with selectors' },\n ];\n\n return (\n
\n \n
Sidebar
\n \n Other element\n
\n );\n}\n```\n\n## Restart / Resume Tour\n\n```tsx\nfunction App() {\n const [run, setRun] = useState(false);\n const [initialStepIndex, setInitialStepIndex] = useState(0);\n\n const handleStart = () => {\n setInitialStepIndex(0);\n setRun(true);\n };\n\n const handleResume = (fromStep: number) => {\n setInitialStepIndex(fromStep);\n setRun(true);\n };\n\n return (\n
\n {\n if ([STATUS.FINISHED, STATUS.SKIPPED].includes(data.status)) {\n setRun(false);\n }\n }}\n />\n \n \n
\n );\n}\n```\n\n## Center Placement (Modal Style)\n\n```tsx\n{\n target: 'body',\n placement: 'center',\n content: (\n
\n

Welcome!

\n

This appears as a centered modal overlay.

\n
\n ),\n // Center placement automatically hides beacon and arrow\n}\n```\n","skills/react-joyride/SKILL.md":"---\nname: react-joyride\ndescription: >-\n Guide for implementing, configuring, and debugging React Joyride v3 guided tours.\n Use this skill whenever the user mentions joyride, guided tour, onboarding tour,\n walkthrough, tooltip tour, step-by-step guide, product tour, or wants to highlight\n UI elements sequentially. Also use when debugging tour issues like tooltips not\n appearing, targets not found, or controlled mode problems. This skill covers the\n useJoyride hook, Joyride component, step configuration, events, controls, custom\n components, and styling.\nlicense: MIT\nmetadata:\n author: gilbarbara\n version: \"3.0.0\"\n---\n\n# React Joyride v3\n\nCreate guided tours in React apps. Two public APIs: the `useJoyride()` hook (recommended) and the `` component.\n\nOnline docs: https://v3.react-joyride.com\n\n## Quick Start\n\n### Using the hook (recommended)\n\n```tsx\nimport { useJoyride, STATUS, Status } from 'react-joyride';\n\nfunction App() {\n const { Tour } = useJoyride({\n continuous: true,\n run: true,\n steps: [\n { target: '.my-element', content: 'This is the first step', title: 'Welcome' },\n { target: '#sidebar', content: 'Navigate here', placement: 'right' },\n ],\n onEvent: (data) => {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n // Tour ended\n }\n },\n });\n\n return
{Tour}{/* rest of app */}
;\n}\n```\n\n### Using the component\n\n```tsx\nimport { Joyride, STATUS, Status } from 'react-joyride';\n\nfunction App() {\n return (\n {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n // Tour ended\n }\n }}\n />\n );\n}\n```\n\nThe hook returns `{ controls, failures, on, state, step, Tour }`. Render `Tour` in your JSX.\n\nDocs: https://v3.react-joyride.com/docs/getting-started\n\n## Core Concepts\n\nThe tour has two state dimensions:\n\n**Tour Status**: `idle -> ready -> waiting -> running <-> paused -> finished | skipped`\n- `idle`: No steps loaded\n- `ready`: Steps loaded, waiting for `run: true`\n- `waiting`: `run=true` but steps loading async (transitions to running when steps arrive)\n- `running`: Tour active\n- `paused`: Tour paused (controlled mode at COMPLETE, or `stop()` called)\n- `finished` / `skipped`: Tour ended\n\n**Step Lifecycle** (per step): `init -> ready -> beacon_before -> beacon -> tooltip_before -> tooltip -> complete`\n- `*_before` phases: scrolling and positioning happen here\n- `beacon`: Pulsing indicator shown (skipped when `continuous` + navigating, `skipBeacon`, or `placement: 'center'`)\n- `tooltip`: The tooltip is visible and interactive\n\nDocs: https://v3.react-joyride.com/docs/how-it-works\n\n## Step Configuration\n\nEach step requires `target` and `content`. All other fields are optional.\n\n```tsx\n{\n target: '.my-element', // CSS selector, HTMLElement, React ref, or () => HTMLElement\n content: 'Step body text', // ReactNode\n title: 'Optional title', // ReactNode\n placement: 'bottom', // Default. Also: top, left, right, *-start, *-end, auto, center\n id: 'unique-id', // Optional identifier\n data: { custom: 'data' }, // Attached to event callbacks\n}\n```\n\n### Target types\n\n```tsx\n// CSS selector\n{ target: '.sidebar-nav' }\n// HTMLElement\n{ target: document.getElementById('my-el') }\n// React ref\nconst ref = useRef(null);\n{ target: ref }\n// Function (evaluated each lifecycle)\n{ target: () => document.querySelector('.dynamic-element') }\n```\n\n### Common step options (override per-step)\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `placement` | `'bottom'` | Tooltip position. Use `'center'` for modal-style (requires `target: 'body'`) |\n| `skipBeacon` | `false` | Skip beacon, show tooltip directly |\n| `buttons` | `['back','close','primary']` | Buttons in tooltip. Add `'skip'` for skip button |\n| `hideOverlay` | `false` | Don't show dark overlay |\n| `blockTargetInteraction` | `false` | Block clicks on highlighted element |\n| `before` | - | `(data) => Promise` — async hook before step shows |\n| `after` | - | `(data) => void` — fire-and-forget hook after step completes |\n| `skipScroll` | `false` | Don't scroll to target |\n| `scrollTarget` | - | Scroll to this element instead of `target` |\n| `spotlightTarget` | - | Highlight this element instead of `target` |\n| `spotlightPadding` | `10` | Padding around spotlight. Number or `{ top, right, bottom, left }` |\n| `targetWaitTimeout` | `1000` | ms to wait for target to appear. `0` = no waiting |\n| `beforeTimeout` | `5000` | ms to wait for `before` hook. `0` = no timeout |\n\nAll `Options` fields can be set globally via `options` prop or per-step. Per-step values override global.\n\nDocs: https://v3.react-joyride.com/docs/step | https://v3.react-joyride.com/docs/props/options\n\n## Uncontrolled vs Controlled\n\n### Uncontrolled (default — strongly preferred)\n\nThe tour manages step navigation internally. This is the right choice for most use cases.\n\n**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.\n\n```tsx\nconst { Tour } = useJoyride({\n continuous: true,\n run: isRunning,\n steps: [\n { target: '.nav', content: 'Navigation' },\n {\n target: '.dropdown-item',\n content: 'Inside the dropdown',\n before: () => {\n // Open dropdown and wait for animation — tour waits automatically\n openDropdown();\n return new Promise(resolve => setTimeout(resolve, 300));\n },\n after: () => closeDropdown(), // Clean up after step (fire-and-forget)\n },\n { target: '.main-content', content: 'Main content' },\n ],\n onEvent: (data) => {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n setIsRunning(false);\n }\n },\n});\n```\n\n### Controlled (with `stepIndex`) — use sparingly\n\nOnly 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).\n\n```tsx\nconst [stepIndex, setStepIndex] = useState(0);\nconst [run, setRun] = useState(true);\n\nconst { Tour } = useJoyride({\n continuous: true,\n run,\n stepIndex, // This makes it controlled\n steps,\n onEvent: (data) => {\n const { action, index, status, type } = data;\n\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(status)) {\n setRun(false);\n return;\n }\n\n if (type === 'step:after' || type === 'error:target_not_found') {\n setStepIndex(index + (action === 'prev' ? -1 : 1));\n }\n },\n});\n```\n\n**Controlled mode rules:**\n- `go()` and `reset()` are disabled (logged warning)\n- You must update `stepIndex` in response to events\n- The tour pauses at COMPLETE — you must advance it\n- Prefer uncontrolled mode with `before`/`after` hooks unless you have a strong reason for external index management\n\n## Event System\n\n### `onEvent` callback\n\n```tsx\nonEvent: (data: EventData, controls: Controls) => void\n```\n\nThe `data` object contains the full tour state plus event-specific fields. The `controls` object lets you programmatically control the tour.\n\n### Event types (in order per step)\n\n| Event | When |\n|-------|------|\n| `tour:start` | Tour begins |\n| `step:before_hook` | `before` hook is called |\n| `step:before` | Target found, step about to render |\n| `scroll:start` | Scrolling to target |\n| `scroll:end` | Scroll complete |\n| `beacon` | Beacon shown |\n| `tooltip` | Tooltip shown |\n| `step:after` | User navigated (next/prev/close/skip) |\n| `step:after_hook` | `after` hook called |\n| `tour:end` | Tour finished or skipped |\n| `tour:status` | Status changed (on stop/reset) |\n| `error:target_not_found` | Target element not found |\n| `error` | Generic error |\n\n### Event subscription with `on()`\n\n```tsx\nconst { on, Tour } = useJoyride({ ... });\n\nuseEffect(() => {\n const unsubscribe = on('tooltip', (data, controls) => {\n analytics.track('tour_step_viewed', { step: data.index });\n });\n return unsubscribe;\n}, [on]);\n```\n\nDocs: https://v3.react-joyride.com/docs/events\n\n## Controls\n\nAvailable via `useJoyride()` return value or `onEvent` second argument:\n\n| Method | Description |\n|--------|-------------|\n| `next()` | Advance to next step |\n| `prev()` | Go to previous step |\n| `close(origin?)` | Close current step, advance |\n| `skip(origin?)` | Skip the tour entirely |\n| `start(index?)` | Start the tour |\n| `stop(advance?)` | Stop (pause) the tour |\n| `go(index)` | Jump to step (uncontrolled only) |\n| `reset(restart?)` | Reset tour (uncontrolled only) |\n| `open()` | Open tooltip for current step |\n| `info()` | Get current state |\n\nDocs: https://v3.react-joyride.com/docs/hook\n\n## Styling & Theming\n\nThree layers of customization (from simple to full control):\n\n### 1. Color options (simplest)\n\n```tsx\noptions: {\n primaryColor: '#1976d2', // Buttons and beacon\n backgroundColor: '#1a1a2e', // Tooltip background\n textColor: '#ffffff', // Tooltip text\n overlayColor: 'rgba(0,0,0,0.7)', // Overlay backdrop\n arrowColor: '#1a1a2e', // Arrow (match background)\n}\n```\n\n### 2. Styles override\n\n```tsx\nstyles: {\n tooltip: { borderRadius: 12 },\n buttonPrimary: { backgroundColor: '#1976d2' },\n buttonBack: { color: '#666' },\n spotlight: { borderRadius: 8 },\n}\n```\n\nStyle keys: `arrow`, `beacon`, `beaconInner`, `beaconOuter`, `beaconWrapper`, `buttonBack`, `buttonClose`, `buttonPrimary`, `buttonSkip`, `floater`, `loader`, `overlay`, `tooltip`, `tooltipContainer`, `tooltipContent`, `tooltipFooter`, `tooltipFooterSpacer`, `tooltipTitle`\n\n### 3. Custom components (full control)\n\nSee next section.\n\nDocs: https://v3.react-joyride.com/docs/props/styles\n\n## Custom Components\n\nReplace any UI component via props. Each receives render props with step data and button handlers.\n\n### Custom Tooltip\n\n```tsx\nimport type { TooltipRenderProps } from 'react-joyride';\n\nfunction MyTooltip({ backProps, index, primaryProps, size, skipProps, step, tooltipProps }: TooltipRenderProps) {\n return (\n
\n {step.title &&

{step.title}

}\n
{step.content}
\n
\n {index > 0 && }\n \n
\n
\n );\n}\n\n// Usage\n\n```\n\n**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.\n\n### Custom Beacon\n\nMust render a `` (placed inside a `\n {/* ... */}\n \n );\n}\n```\n\n## Before/After Hooks\n\n### Async data loading before a step\n\n```tsx\n{\n target: '.user-profile',\n content: 'Here is your profile data',\n before: async () => {\n await fetchUserProfile();\n // Tour waits for this promise to resolve\n },\n beforeTimeout: 10000, // Allow up to 10s\n}\n```\n\n### Analytics tracking after a step\n\n```tsx\n{\n target: '.feature',\n content: 'Check out this feature',\n after: (data) => {\n // Fire-and-forget — does not block the tour\n analytics.track('tour_step_completed', {\n stepIndex: data.index,\n action: data.action,\n });\n },\n}\n```\n\n### Delayed transitions (e.g., waiting for animation)\n\n```tsx\n{\n target: '.sidebar',\n content: 'The sidebar',\n before: ({ action }) => {\n // Only delay when navigating forward (not on back)\n const ms = action === ACTIONS.PREV ? 0 : 300;\n return new Promise(resolve => setTimeout(resolve, ms));\n },\n}\n```\n\n## Custom Tooltip Component\n\n```tsx\nimport type { TooltipRenderProps } from 'react-joyride';\n\nfunction CustomTooltip({\n backProps,\n closeProps,\n index,\n isLastStep,\n primaryProps,\n size,\n skipProps,\n step,\n tooltipProps,\n}: TooltipRenderProps) {\n return (\n \n {step.title &&

{step.title}

}\n
{step.content}
\n\n
\n {step.buttons.includes('skip') && !isLastStep && (\n \n )}\n
\n {index > 0 && (\n \n )}\n \n
\n
\n \n );\n}\n\n// Usage:\n// \n// or in useJoyride: useJoyride({ tooltipComponent: CustomTooltip, ... })\n```\n\n## Event Subscription with `on()`\n\n```tsx\nfunction App() {\n const { on, Tour } = useJoyride({\n steps,\n run: true,\n continuous: true,\n });\n\n useEffect(() => {\n const unsubs = [\n on('tour:start', (data) => {\n console.log('Tour started');\n }),\n on('tooltip', (data) => {\n analytics.track('step_viewed', { index: data.index });\n }),\n on('tour:end', (data) => {\n const wasSkipped = data.status === 'skipped';\n analytics.track('tour_ended', { skipped: wasSkipped, lastStep: data.index });\n }),\n ];\n\n return () => unsubs.forEach(unsub => unsub());\n }, [on]);\n\n return
{Tour}
;\n}\n```\n\n## Dynamic Steps\n\n```tsx\nfunction App() {\n const [steps, setSteps] = useState([]);\n\n useEffect(() => {\n // Build steps based on feature flags, user role, etc.\n const dynamicSteps: Step[] = [\n { target: '.dashboard', content: 'Welcome to your dashboard' },\n ];\n\n if (user.isAdmin) {\n dynamicSteps.push({\n target: '.admin-panel',\n content: 'Admin controls are here',\n });\n }\n\n if (featureFlags.newSearch) {\n dynamicSteps.push({\n target: '.search-bar',\n content: 'Try the new search',\n });\n }\n\n setSteps(dynamicSteps);\n }, [user, featureFlags]);\n\n return (\n 0}\n steps={steps}\n continuous\n />\n );\n}\n```\n\n## React Ref Targets\n\n```tsx\nfunction App() {\n const sidebarRef = useRef(null);\n const buttonRef = useRef(null);\n\n const steps: Step[] = [\n { target: sidebarRef, content: 'Navigation sidebar' },\n { target: buttonRef, content: 'Click here to create' },\n { target: '.css-selector', content: 'Mix refs with selectors' },\n ];\n\n return (\n
\n \n
Sidebar
\n \n Other element\n
\n );\n}\n```\n\n## Restart / Resume Tour\n\n```tsx\nfunction App() {\n const [run, setRun] = useState(false);\n const [initialStepIndex, setInitialStepIndex] = useState(0);\n\n const handleStart = () => {\n setInitialStepIndex(0);\n setRun(true);\n };\n\n const handleResume = (fromStep: number) => {\n setInitialStepIndex(fromStep);\n setRun(true);\n };\n\n return (\n
\n {\n if ([STATUS.FINISHED, STATUS.SKIPPED].includes(data.status)) {\n setRun(false);\n }\n }}\n />\n \n \n
\n );\n}\n```\n\n## Center Placement (Modal Style)\n\n```tsx\n{\n target: 'body',\n placement: 'center',\n content: (\n
\n

Welcome!

\n

This appears as a centered modal overlay.

\n
\n ),\n // Center placement automatically hides beacon and arrow\n}\n```\n","isInternal":false,"tokens":1790,"sizeBytes":7109},{"name":"SKILL.md","path":"skills/react-joyride/SKILL.md","rawUrl":"https://raw.githubusercontent.com/gilbarbara/react-joyride/HEAD/skills/react-joyride/SKILL.md","title":"react-joyride","category":"anthropic-skill","format":"markdown","content":"---\nname: react-joyride\ndescription: >-\n Guide for implementing, configuring, and debugging React Joyride v3 guided tours.\n Use this skill whenever the user mentions joyride, guided tour, onboarding tour,\n walkthrough, tooltip tour, step-by-step guide, product tour, or wants to highlight\n UI elements sequentially. Also use when debugging tour issues like tooltips not\n appearing, targets not found, or controlled mode problems. This skill covers the\n useJoyride hook, Joyride component, step configuration, events, controls, custom\n components, and styling.\nlicense: MIT\nmetadata:\n author: gilbarbara\n version: \"3.0.0\"\n---\n\n# React Joyride v3\n\nCreate guided tours in React apps. Two public APIs: the `useJoyride()` hook (recommended) and the `` component.\n\nOnline docs: https://v3.react-joyride.com\n\n## Quick Start\n\n### Using the hook (recommended)\n\n```tsx\nimport { useJoyride, STATUS, Status } from 'react-joyride';\n\nfunction App() {\n const { Tour } = useJoyride({\n continuous: true,\n run: true,\n steps: [\n { target: '.my-element', content: 'This is the first step', title: 'Welcome' },\n { target: '#sidebar', content: 'Navigate here', placement: 'right' },\n ],\n onEvent: (data) => {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n // Tour ended\n }\n },\n });\n\n return
{Tour}{/* rest of app */}
;\n}\n```\n\n### Using the component\n\n```tsx\nimport { Joyride, STATUS, Status } from 'react-joyride';\n\nfunction App() {\n return (\n {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n // Tour ended\n }\n }}\n />\n );\n}\n```\n\nThe hook returns `{ controls, failures, on, state, step, Tour }`. Render `Tour` in your JSX.\n\nDocs: https://v3.react-joyride.com/docs/getting-started\n\n## Core Concepts\n\nThe tour has two state dimensions:\n\n**Tour Status**: `idle -> ready -> waiting -> running <-> paused -> finished | skipped`\n- `idle`: No steps loaded\n- `ready`: Steps loaded, waiting for `run: true`\n- `waiting`: `run=true` but steps loading async (transitions to running when steps arrive)\n- `running`: Tour active\n- `paused`: Tour paused (controlled mode at COMPLETE, or `stop()` called)\n- `finished` / `skipped`: Tour ended\n\n**Step Lifecycle** (per step): `init -> ready -> beacon_before -> beacon -> tooltip_before -> tooltip -> complete`\n- `*_before` phases: scrolling and positioning happen here\n- `beacon`: Pulsing indicator shown (skipped when `continuous` + navigating, `skipBeacon`, or `placement: 'center'`)\n- `tooltip`: The tooltip is visible and interactive\n\nDocs: https://v3.react-joyride.com/docs/how-it-works\n\n## Step Configuration\n\nEach step requires `target` and `content`. All other fields are optional.\n\n```tsx\n{\n target: '.my-element', // CSS selector, HTMLElement, React ref, or () => HTMLElement\n content: 'Step body text', // ReactNode\n title: 'Optional title', // ReactNode\n placement: 'bottom', // Default. Also: top, left, right, *-start, *-end, auto, center\n id: 'unique-id', // Optional identifier\n data: { custom: 'data' }, // Attached to event callbacks\n}\n```\n\n### Target types\n\n```tsx\n// CSS selector\n{ target: '.sidebar-nav' }\n// HTMLElement\n{ target: document.getElementById('my-el') }\n// React ref\nconst ref = useRef(null);\n{ target: ref }\n// Function (evaluated each lifecycle)\n{ target: () => document.querySelector('.dynamic-element') }\n```\n\n### Common step options (override per-step)\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `placement` | `'bottom'` | Tooltip position. Use `'center'` for modal-style (requires `target: 'body'`) |\n| `skipBeacon` | `false` | Skip beacon, show tooltip directly |\n| `buttons` | `['back','close','primary']` | Buttons in tooltip. Add `'skip'` for skip button |\n| `hideOverlay` | `false` | Don't show dark overlay |\n| `blockTargetInteraction` | `false` | Block clicks on highlighted element |\n| `before` | - | `(data) => Promise` — async hook before step shows |\n| `after` | - | `(data) => void` — fire-and-forget hook after step completes |\n| `skipScroll` | `false` | Don't scroll to target |\n| `scrollTarget` | - | Scroll to this element instead of `target` |\n| `spotlightTarget` | - | Highlight this element instead of `target` |\n| `spotlightPadding` | `10` | Padding around spotlight. Number or `{ top, right, bottom, left }` |\n| `targetWaitTimeout` | `1000` | ms to wait for target to appear. `0` = no waiting |\n| `beforeTimeout` | `5000` | ms to wait for `before` hook. `0` = no timeout |\n\nAll `Options` fields can be set globally via `options` prop or per-step. Per-step values override global.\n\nDocs: https://v3.react-joyride.com/docs/step | https://v3.react-joyride.com/docs/props/options\n\n## Uncontrolled vs Controlled\n\n### Uncontrolled (default — strongly preferred)\n\nThe tour manages step navigation internally. This is the right choice for most use cases.\n\n**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.\n\n```tsx\nconst { Tour } = useJoyride({\n continuous: true,\n run: isRunning,\n steps: [\n { target: '.nav', content: 'Navigation' },\n {\n target: '.dropdown-item',\n content: 'Inside the dropdown',\n before: () => {\n // Open dropdown and wait for animation — tour waits automatically\n openDropdown();\n return new Promise(resolve => setTimeout(resolve, 300));\n },\n after: () => closeDropdown(), // Clean up after step (fire-and-forget)\n },\n { target: '.main-content', content: 'Main content' },\n ],\n onEvent: (data) => {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n setIsRunning(false);\n }\n },\n});\n```\n\n### Controlled (with `stepIndex`) — use sparingly\n\nOnly 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).\n\n```tsx\nconst [stepIndex, setStepIndex] = useState(0);\nconst [run, setRun] = useState(true);\n\nconst { Tour } = useJoyride({\n continuous: true,\n run,\n stepIndex, // This makes it controlled\n steps,\n onEvent: (data) => {\n const { action, index, status, type } = data;\n\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(status)) {\n setRun(false);\n return;\n }\n\n if (type === 'step:after' || type === 'error:target_not_found') {\n setStepIndex(index + (action === 'prev' ? -1 : 1));\n }\n },\n});\n```\n\n**Controlled mode rules:**\n- `go()` and `reset()` are disabled (logged warning)\n- You must update `stepIndex` in response to events\n- The tour pauses at COMPLETE — you must advance it\n- Prefer uncontrolled mode with `before`/`after` hooks unless you have a strong reason for external index management\n\n## Event System\n\n### `onEvent` callback\n\n```tsx\nonEvent: (data: EventData, controls: Controls) => void\n```\n\nThe `data` object contains the full tour state plus event-specific fields. The `controls` object lets you programmatically control the tour.\n\n### Event types (in order per step)\n\n| Event | When |\n|-------|------|\n| `tour:start` | Tour begins |\n| `step:before_hook` | `before` hook is called |\n| `step:before` | Target found, step about to render |\n| `scroll:start` | Scrolling to target |\n| `scroll:end` | Scroll complete |\n| `beacon` | Beacon shown |\n| `tooltip` | Tooltip shown |\n| `step:after` | User navigated (next/prev/close/skip) |\n| `step:after_hook` | `after` hook called |\n| `tour:end` | Tour finished or skipped |\n| `tour:status` | Status changed (on stop/reset) |\n| `error:target_not_found` | Target element not found |\n| `error` | Generic error |\n\n### Event subscription with `on()`\n\n```tsx\nconst { on, Tour } = useJoyride({ ... });\n\nuseEffect(() => {\n const unsubscribe = on('tooltip', (data, controls) => {\n analytics.track('tour_step_viewed', { step: data.index });\n });\n return unsubscribe;\n}, [on]);\n```\n\nDocs: https://v3.react-joyride.com/docs/events\n\n## Controls\n\nAvailable via `useJoyride()` return value or `onEvent` second argument:\n\n| Method | Description |\n|--------|-------------|\n| `next()` | Advance to next step |\n| `prev()` | Go to previous step |\n| `close(origin?)` | Close current step, advance |\n| `skip(origin?)` | Skip the tour entirely |\n| `start(index?)` | Start the tour |\n| `stop(advance?)` | Stop (pause) the tour |\n| `go(index)` | Jump to step (uncontrolled only) |\n| `reset(restart?)` | Reset tour (uncontrolled only) |\n| `open()` | Open tooltip for current step |\n| `info()` | Get current state |\n\nDocs: https://v3.react-joyride.com/docs/hook\n\n## Styling & Theming\n\nThree layers of customization (from simple to full control):\n\n### 1. Color options (simplest)\n\n```tsx\noptions: {\n primaryColor: '#1976d2', // Buttons and beacon\n backgroundColor: '#1a1a2e', // Tooltip background\n textColor: '#ffffff', // Tooltip text\n overlayColor: 'rgba(0,0,0,0.7)', // Overlay backdrop\n arrowColor: '#1a1a2e', // Arrow (match background)\n}\n```\n\n### 2. Styles override\n\n```tsx\nstyles: {\n tooltip: { borderRadius: 12 },\n buttonPrimary: { backgroundColor: '#1976d2' },\n buttonBack: { color: '#666' },\n spotlight: { borderRadius: 8 },\n}\n```\n\nStyle keys: `arrow`, `beacon`, `beaconInner`, `beaconOuter`, `beaconWrapper`, `buttonBack`, `buttonClose`, `buttonPrimary`, `buttonSkip`, `floater`, `loader`, `overlay`, `tooltip`, `tooltipContainer`, `tooltipContent`, `tooltipFooter`, `tooltipFooterSpacer`, `tooltipTitle`\n\n### 3. Custom components (full control)\n\nSee next section.\n\nDocs: https://v3.react-joyride.com/docs/props/styles\n\n## Custom Components\n\nReplace any UI component via props. Each receives render props with step data and button handlers.\n\n### Custom Tooltip\n\n```tsx\nimport type { TooltipRenderProps } from 'react-joyride';\n\nfunction MyTooltip({ backProps, index, primaryProps, size, skipProps, step, tooltipProps }: TooltipRenderProps) {\n return (\n
\n {step.title &&

{step.title}

}\n
{step.content}
\n
\n {index > 0 && }\n \n
\n
\n );\n}\n\n// Usage\n\n```\n\n**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.\n\n### Custom Beacon\n\nMust render a `` (placed inside a `\n {/* ... */}\n \n );\n}\n```\n\n## Before/After Hooks\n\n### Async data loading before a step\n\n```tsx\n{\n target: '.user-profile',\n content: 'Here is your profile data',\n before: async () => {\n await fetchUserProfile();\n // Tour waits for this promise to resolve\n },\n beforeTimeout: 10000, // Allow up to 10s\n}\n```\n\n### Analytics tracking after a step\n\n```tsx\n{\n target: '.feature',\n content: 'Check out this feature',\n after: (data) => {\n // Fire-and-forget — does not block the tour\n analytics.track('tour_step_completed', {\n stepIndex: data.index,\n action: data.action,\n });\n },\n}\n```\n\n### Delayed transitions (e.g., waiting for animation)\n\n```tsx\n{\n target: '.sidebar',\n content: 'The sidebar',\n before: ({ action }) => {\n // Only delay when navigating forward (not on back)\n const ms = action === ACTIONS.PREV ? 0 : 300;\n return new Promise(resolve => setTimeout(resolve, ms));\n },\n}\n```\n\n## Custom Tooltip Component\n\n```tsx\nimport type { TooltipRenderProps } from 'react-joyride';\n\nfunction CustomTooltip({\n backProps,\n closeProps,\n index,\n isLastStep,\n primaryProps,\n size,\n skipProps,\n step,\n tooltipProps,\n}: TooltipRenderProps) {\n return (\n \n {step.title &&

{step.title}

}\n
{step.content}
\n\n
\n {step.buttons.includes('skip') && !isLastStep && (\n \n )}\n
\n {index > 0 && (\n \n )}\n \n
\n
\n \n );\n}\n\n// Usage:\n// \n// or in useJoyride: useJoyride({ tooltipComponent: CustomTooltip, ... })\n```\n\n## Event Subscription with `on()`\n\n```tsx\nfunction App() {\n const { on, Tour } = useJoyride({\n steps,\n run: true,\n continuous: true,\n });\n\n useEffect(() => {\n const unsubs = [\n on('tour:start', (data) => {\n console.log('Tour started');\n }),\n on('tooltip', (data) => {\n analytics.track('step_viewed', { index: data.index });\n }),\n on('tour:end', (data) => {\n const wasSkipped = data.status === 'skipped';\n analytics.track('tour_ended', { skipped: wasSkipped, lastStep: data.index });\n }),\n ];\n\n return () => unsubs.forEach(unsub => unsub());\n }, [on]);\n\n return
{Tour}
;\n}\n```\n\n## Dynamic Steps\n\n```tsx\nfunction App() {\n const [steps, setSteps] = useState([]);\n\n useEffect(() => {\n // Build steps based on feature flags, user role, etc.\n const dynamicSteps: Step[] = [\n { target: '.dashboard', content: 'Welcome to your dashboard' },\n ];\n\n if (user.isAdmin) {\n dynamicSteps.push({\n target: '.admin-panel',\n content: 'Admin controls are here',\n });\n }\n\n if (featureFlags.newSearch) {\n dynamicSteps.push({\n target: '.search-bar',\n content: 'Try the new search',\n });\n }\n\n setSteps(dynamicSteps);\n }, [user, featureFlags]);\n\n return (\n 0}\n steps={steps}\n continuous\n />\n );\n}\n```\n\n## React Ref Targets\n\n```tsx\nfunction App() {\n const sidebarRef = useRef(null);\n const buttonRef = useRef(null);\n\n const steps: Step[] = [\n { target: sidebarRef, content: 'Navigation sidebar' },\n { target: buttonRef, content: 'Click here to create' },\n { target: '.css-selector', content: 'Mix refs with selectors' },\n ];\n\n return (\n
\n \n
Sidebar
\n \n Other element\n
\n );\n}\n```\n\n## Restart / Resume Tour\n\n```tsx\nfunction App() {\n const [run, setRun] = useState(false);\n const [initialStepIndex, setInitialStepIndex] = useState(0);\n\n const handleStart = () => {\n setInitialStepIndex(0);\n setRun(true);\n };\n\n const handleResume = (fromStep: number) => {\n setInitialStepIndex(fromStep);\n setRun(true);\n };\n\n return (\n
\n {\n if ([STATUS.FINISHED, STATUS.SKIPPED].includes(data.status)) {\n setRun(false);\n }\n }}\n />\n \n \n
\n );\n}\n```\n\n## Center Placement (Modal Style)\n\n```tsx\n{\n target: 'body',\n placement: 'center',\n content: (\n
\n

Welcome!

\n

This appears as a centered modal overlay.

\n
\n ),\n // Center placement automatically hides beacon and arrow\n}\n```\n\n\n---\nname: react-joyride\ndescription: >-\n Guide for implementing, configuring, and debugging React Joyride v3 guided tours.\n Use this skill whenever the user mentions joyride, guided tour, onboarding tour,\n walkthrough, tooltip tour, step-by-step guide, product tour, or wants to highlight\n UI elements sequentially. Also use when debugging tour issues like tooltips not\n appearing, targets not found, or controlled mode problems. This skill covers the\n useJoyride hook, Joyride component, step configuration, events, controls, custom\n components, and styling.\nlicense: MIT\nmetadata:\n author: gilbarbara\n version: \"3.0.0\"\n---\n\n# React Joyride v3\n\nCreate guided tours in React apps. Two public APIs: the `useJoyride()` hook (recommended) and the `` component.\n\nOnline docs: https://v3.react-joyride.com\n\n## Quick Start\n\n### Using the hook (recommended)\n\n```tsx\nimport { useJoyride, STATUS, Status } from 'react-joyride';\n\nfunction App() {\n const { Tour } = useJoyride({\n continuous: true,\n run: true,\n steps: [\n { target: '.my-element', content: 'This is the first step', title: 'Welcome' },\n { target: '#sidebar', content: 'Navigate here', placement: 'right' },\n ],\n onEvent: (data) => {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n // Tour ended\n }\n },\n });\n\n return
{Tour}{/* rest of app */}
;\n}\n```\n\n### Using the component\n\n```tsx\nimport { Joyride, STATUS, Status } from 'react-joyride';\n\nfunction App() {\n return (\n {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n // Tour ended\n }\n }}\n />\n );\n}\n```\n\nThe hook returns `{ controls, failures, on, state, step, Tour }`. Render `Tour` in your JSX.\n\nDocs: https://v3.react-joyride.com/docs/getting-started\n\n## Core Concepts\n\nThe tour has two state dimensions:\n\n**Tour Status**: `idle -> ready -> waiting -> running <-> paused -> finished | skipped`\n- `idle`: No steps loaded\n- `ready`: Steps loaded, waiting for `run: true`\n- `waiting`: `run=true` but steps loading async (transitions to running when steps arrive)\n- `running`: Tour active\n- `paused`: Tour paused (controlled mode at COMPLETE, or `stop()` called)\n- `finished` / `skipped`: Tour ended\n\n**Step Lifecycle** (per step): `init -> ready -> beacon_before -> beacon -> tooltip_before -> tooltip -> complete`\n- `*_before` phases: scrolling and positioning happen here\n- `beacon`: Pulsing indicator shown (skipped when `continuous` + navigating, `skipBeacon`, or `placement: 'center'`)\n- `tooltip`: The tooltip is visible and interactive\n\nDocs: https://v3.react-joyride.com/docs/how-it-works\n\n## Step Configuration\n\nEach step requires `target` and `content`. All other fields are optional.\n\n```tsx\n{\n target: '.my-element', // CSS selector, HTMLElement, React ref, or () => HTMLElement\n content: 'Step body text', // ReactNode\n title: 'Optional title', // ReactNode\n placement: 'bottom', // Default. Also: top, left, right, *-start, *-end, auto, center\n id: 'unique-id', // Optional identifier\n data: { custom: 'data' }, // Attached to event callbacks\n}\n```\n\n### Target types\n\n```tsx\n// CSS selector\n{ target: '.sidebar-nav' }\n// HTMLElement\n{ target: document.getElementById('my-el') }\n// React ref\nconst ref = useRef(null);\n{ target: ref }\n// Function (evaluated each lifecycle)\n{ target: () => document.querySelector('.dynamic-element') }\n```\n\n### Common step options (override per-step)\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `placement` | `'bottom'` | Tooltip position. Use `'center'` for modal-style (requires `target: 'body'`) |\n| `skipBeacon` | `false` | Skip beacon, show tooltip directly |\n| `buttons` | `['back','close','primary']` | Buttons in tooltip. Add `'skip'` for skip button |\n| `hideOverlay` | `false` | Don't show dark overlay |\n| `blockTargetInteraction` | `false` | Block clicks on highlighted element |\n| `before` | - | `(data) => Promise` — async hook before step shows |\n| `after` | - | `(data) => void` — fire-and-forget hook after step completes |\n| `skipScroll` | `false` | Don't scroll to target |\n| `scrollTarget` | - | Scroll to this element instead of `target` |\n| `spotlightTarget` | - | Highlight this element instead of `target` |\n| `spotlightPadding` | `10` | Padding around spotlight. Number or `{ top, right, bottom, left }` |\n| `targetWaitTimeout` | `1000` | ms to wait for target to appear. `0` = no waiting |\n| `beforeTimeout` | `5000` | ms to wait for `before` hook. `0` = no timeout |\n\nAll `Options` fields can be set globally via `options` prop or per-step. Per-step values override global.\n\nDocs: https://v3.react-joyride.com/docs/step | https://v3.react-joyride.com/docs/props/options\n\n## Uncontrolled vs Controlled\n\n### Uncontrolled (default — strongly preferred)\n\nThe tour manages step navigation internally. This is the right choice for most use cases.\n\n**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.\n\n```tsx\nconst { Tour } = useJoyride({\n continuous: true,\n run: isRunning,\n steps: [\n { target: '.nav', content: 'Navigation' },\n {\n target: '.dropdown-item',\n content: 'Inside the dropdown',\n before: () => {\n // Open dropdown and wait for animation — tour waits automatically\n openDropdown();\n return new Promise(resolve => setTimeout(resolve, 300));\n },\n after: () => closeDropdown(), // Clean up after step (fire-and-forget)\n },\n { target: '.main-content', content: 'Main content' },\n ],\n onEvent: (data) => {\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(data.status)) {\n setIsRunning(false);\n }\n },\n});\n```\n\n### Controlled (with `stepIndex`) — use sparingly\n\nOnly 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).\n\n```tsx\nconst [stepIndex, setStepIndex] = useState(0);\nconst [run, setRun] = useState(true);\n\nconst { Tour } = useJoyride({\n continuous: true,\n run,\n stepIndex, // This makes it controlled\n steps,\n onEvent: (data) => {\n const { action, index, status, type } = data;\n\n if (([STATUS.FINISHED, STATUS.SKIPPED] as Status).includes(status)) {\n setRun(false);\n return;\n }\n\n if (type === 'step:after' || type === 'error:target_not_found') {\n setStepIndex(index + (action === 'prev' ? -1 : 1));\n }\n },\n});\n```\n\n**Controlled mode rules:**\n- `go()` and `reset()` are disabled (logged warning)\n- You must update `stepIndex` in response to events\n- The tour pauses at COMPLETE — you must advance it\n- Prefer uncontrolled mode with `before`/`after` hooks unless you have a strong reason for external index management\n\n## Event System\n\n### `onEvent` callback\n\n```tsx\nonEvent: (data: EventData, controls: Controls) => void\n```\n\nThe `data` object contains the full tour state plus event-specific fields. The `controls` object lets you programmatically control the tour.\n\n### Event types (in order per step)\n\n| Event | When |\n|-------|------|\n| `tour:start` | Tour begins |\n| `step:before_hook` | `before` hook is called |\n| `step:before` | Target found, step about to render |\n| `scroll:start` | Scrolling to target |\n| `scroll:end` | Scroll complete |\n| `beacon` | Beacon shown |\n| `tooltip` | Tooltip shown |\n| `step:after` | User navigated (next/prev/close/skip) |\n| `step:after_hook` | `after` hook called |\n| `tour:end` | Tour finished or skipped |\n| `tour:status` | Status changed (on stop/reset) |\n| `error:target_not_found` | Target element not found |\n| `error` | Generic error |\n\n### Event subscription with `on()`\n\n```tsx\nconst { on, Tour } = useJoyride({ ... });\n\nuseEffect(() => {\n const unsubscribe = on('tooltip', (data, controls) => {\n analytics.track('tour_step_viewed', { step: data.index });\n });\n return unsubscribe;\n}, [on]);\n```\n\nDocs: https://v3.react-joyride.com/docs/events\n\n## Controls\n\nAvailable via `useJoyride()` return value or `onEvent` second argument:\n\n| Method | Description |\n|--------|-------------|\n| `next()` | Advance to next step |\n| `prev()` | Go to previous step |\n| `close(origin?)` | Close current step, advance |\n| `skip(origin?)` | Skip the tour entirely |\n| `start(index?)` | Start the tour |\n| `stop(advance?)` | Stop (pause) the tour |\n| `go(index)` | Jump to step (uncontrolled only) |\n| `reset(restart?)` | Reset tour (uncontrolled only) |\n| `open()` | Open tooltip for current step |\n| `info()` | Get current state |\n\nDocs: https://v3.react-joyride.com/docs/hook\n\n## Styling & Theming\n\nThree layers of customization (from simple to full control):\n\n### 1. Color options (simplest)\n\n```tsx\noptions: {\n primaryColor: '#1976d2', // Buttons and beacon\n backgroundColor: '#1a1a2e', // Tooltip background\n textColor: '#ffffff', // Tooltip text\n overlayColor: 'rgba(0,0,0,0.7)', // Overlay backdrop\n arrowColor: '#1a1a2e', // Arrow (match background)\n}\n```\n\n### 2. Styles override\n\n```tsx\nstyles: {\n tooltip: { borderRadius: 12 },\n buttonPrimary: { backgroundColor: '#1976d2' },\n buttonBack: { color: '#666' },\n spotlight: { borderRadius: 8 },\n}\n```\n\nStyle keys: `arrow`, `beacon`, `beaconInner`, `beaconOuter`, `beaconWrapper`, `buttonBack`, `buttonClose`, `buttonPrimary`, `buttonSkip`, `floater`, `loader`, `overlay`, `tooltip`, `tooltipContainer`, `tooltipContent`, `tooltipFooter`, `tooltipFooterSpacer`, `tooltipTitle`\n\n### 3. Custom components (full control)\n\nSee next section.\n\nDocs: https://v3.react-joyride.com/docs/props/styles\n\n## Custom Components\n\nReplace any UI component via props. Each receives render props with step data and button handlers.\n\n### Custom Tooltip\n\n```tsx\nimport type { TooltipRenderProps } from 'react-joyride';\n\nfunction MyTooltip({ backProps, index, primaryProps, size, skipProps, step, tooltipProps }: TooltipRenderProps) {\n return (\n
\n {step.title &&

{step.title}

}\n
{step.content}
\n
\n {index > 0 && }\n \n
\n
\n );\n}\n\n// Usage\n\n```\n\n**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.\n\n### Custom Beacon\n\nMust render a `` (placed inside a `