跳到主内容
智客 ZICQ

技能库 智客分类:Agent 工作流 react-joyride

React Joyride

执行、配置和调试的指南 每当用户提到"欢乐之旅","被引导之旅","登机之旅","走通","工具提示之旅","分步向导","产品之旅",或想依次突出UI元素时,就使用这一技能. 同时在调试旅游问题时使用,如工具提示未出现,目标未发现,或控制模式出问题等. 这个技能涵盖了使用Joyride hook,Joyride组件,步骤配置,事件,控制,自定义组件,以及样式.

619 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

执行、配置和调试的指南 每当用户提到"欢乐之旅","被引导之旅","登机之旅","走通","工具提示之旅","分步向导","产品之旅",或想依次突出UI元素时,就使用这一技能. 同时在调试旅游问题时使用,如工具提示未出现,目标未发现,或控制模式出问题等. 这个技能涵盖了使用Joyride hook,Joyride组件,步骤配置,事件,控制,自定义组件,以及样式.

何时用

调试游览问题, 如工具提示未出现, 目标未找到, 或控制模式问题 。 此技能涵盖 Joyride 钩子、 Joyride 组件、 步骤配置、 事件、 控制、 自定义组件和样式

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:React Joyride v3、Quick Start、Using the hook (recommended)、Using the component、Core Concepts、Step Configuration。 其中含规范建议的小节:分步指令。

文件分析

文件分析:除 SKILL.md 外,正文引用了 references/api-props-options.md、references/api-step-state-controls.md、references/api-events-components.md、references/patterns.md,属于带资源的技能包,这些文件按需再读。

官方 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.

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

· 许可:MIT

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
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.
许可
MIT
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 4
  • references/api-props-options.md
  • references/api-step-state-controls.md
  • references/api-events-components.md
  • references/patterns.md

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「react-joyride」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-0548be28d3362d12-%E5%8F%8D%E5%BA%94%E5%96%9C%E6%82%A6.html
请存为 .cursor/skills/react-joyride/SKILL.md 或 .claude/skills/react-joyride/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/gilbarbara/react-joyride 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

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

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

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- 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

相关技能

Agent 工作流

Skill Creator

创造有效技能指南。 当用户想创造出新的技能(或更新现有的技能),以专业知识,工作流程,或工具集成来扩展克洛德的能力时,应该使用这种技能.

Agent 工作流

Clawdhub

使用ClawdHub CLI搜索,安装,更新并发布从taladhub.com的代理技能. 需要获取苍蝇上的新技能时使用,将安装的技能同步到最新版本或特定版本,或者发布 npm-instainddhub CLI 的新/更新的技能文件夹.

Agent 工作流

Agent Team Orchestration

管弦乐团多代理团队,任务设定周期,交接协议,审查工作流程. 使用时间: (1)建立2+特派员队伍,具有不同专业,(2)确定任务路线和生命周期(收录框_ spec_建设_审查_完成),(3)在特派员之间制定交接协议,(4)建立审查和质量关口,(5)管理特派员之间的交流和文物共享.

Agent 工作流

Superpowers

Spec-first,TDD,子代理驱动的软件开发工作流程. 当:(1)构建任何新功能或应用——触发脑暴_计划_子代理执行回路,(2)调试出一个bug或测试失败——触发系统性的根起过程,(3)用户说"让我们构建","帮助我计划","我想添加X",或"这个被打破",(4)完成一个功…