react-onboarding-guide

HTML 요소를 스포트라이팅해 사용자 경험(UX)을 높이는 React 온보딩 가이드 라이브러리 A React onboarding guide library that spotlights HTML elements to improve UX.

한눈에 보기 · Overview

특정 화면 경로(pathname)에 맞는 가이드를 자동으로 찾아, 지정한 DOM 요소를 스포트라이트로 강조하고 단계별 설명 카드를 띄웁니다. 가이드 콘텐츠는 앱에서 정의해 넘겨주며, 라이브러리는 상태 관리·위치 계산·오버레이 렌더링을 담당합니다.

Given the current route (pathname), the library resolves the matching guide, spotlights the target DOM elements, and shows a step-by-step card. You own the guide content; the library handles state, positioning, and the overlay.

• 🔦 스포트라이트 강조 — 대상 요소만 밝게 남기고 주변을 어둡게
• 🧭 경로 기반 매칭 — pathname 으로 화면별 가이드 자동 선택
• 📍 자동 배치 — 뷰포트에 맞춰 카드 위치 자동 조정 (auto)

설치 · Installation

# npm
npm install @sogno6037/react-onboarding-guide

# pnpm
pnpm add @sogno6037/react-onboarding-guide

# yarn
yarn add @sogno6037/react-onboarding-guide

Peer dependencies (앱에 이미 있어야 합니다 · must already exist in your app):

# npm
npm install react react-dom zustand

# pnpm
pnpm add react react-dom zustand

# yarn
yarn add react react-dom zustand

빠른 시작 · Quick Start

1. 가이드 정의 · Define your guides

import type { GuideDefinition } from "@sogno6037/react-onboarding-guide";

export const GUIDES: GuideDefinition[] = [
  {
    key: "search-page",
    title: "검색 화면 가이드",
    match: "/search",
    steps: [
      {
        title: "1. 검색창",
        body: "여기에 키워드를 입력해 원하는 항목을 찾을 수 있어요.",
        target: '[data-guide="search-input"]',
        placement: "bottom",
      },
      {
        title: "2. 필터",
        body: "결과를 조건별로 좁혀 보세요.",
        target: '[data-guide="filter"]',
        placement: "right",
      },
    ],
  },
];

2. 대상 요소에 data-guide 속성 추가 · Tag the target elements

<input data-guide="search-input" type="text" placeholder="검색어 입력" />
<button data-guide="filter">필터</button>

3. 오버레이와 버튼 렌더 · Render the overlay and the button

"use client";

import { GuideOverlay, GuideButton } from "@sogno6037/react-onboarding-guide";
import { usePathname } from "next/navigation"; // 또는 라우터의 현재 경로
import { GUIDES } from "./guides";

export default function Layout({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();

  return (
    <>
      <header>
        <GuideButton guides={GUIDES} pathname={pathname} />
      </header>

      {children}

      {/* 페이지(또는 레이아웃) 최상단에 한 번만 렌더 */}
      <GuideOverlay guides={GUIDES} pathname={pathname} />
    </>
  );
}

💡 pathname 은 사용하는 라우터에서 가져오세요. Next.js App Router는 usePathname(), React Router는 useLocation().pathname 입니다.

컴포넌트 · Components

<GuideOverlay />

가이드가 열리면 화면 전체를 덮고, 현재 단계의 대상 요소를 스포트라이트로 강조하는 컴포넌트입니다. 페이지 또는 레이아웃 최상단에 한 번만 렌더합니다.

Full-screen overlay that spotlights the current step's target. Render once at the top of your page or layout.

| Prop | Type | 설명 · Description | | ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------ | | guides | GuideDefinition[] | 현재 화면에서 사용할 가이드 목록 · Guides available on this screen | | pathname | string | 현재 경로. guides 의 match 와 비교해 가이드를 찾음 · Current route, matched against each guide's match |

<GuideButton />

현재 경로에 해당하는 가이드가 있을 때만 노출되는 "가이드 열기" 버튼입니다. 매칭되는 가이드가 없으면 아무것도 렌더하지 않습니다.

"Open guide" button. Renders only when a guide matches the current route; otherwise renders nothing.

| Prop | Type | 설명 · Description | | ----------- | ------------------- | ------------------------------------------------------------------ | | guides | GuideDefinition[] | 현재 화면에서 사용할 가이드 목록 · Guides available on this screen | | pathname | string | 현재 경로 · Current route | | className | string? | 선택적 클래스명 · Optional class name |

타입 · Types

GuideDefinition

| 필드 · Field | Type | 설명 · Description | | ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | key | string | 가이드 식별자 (스토어에 저장되는 키) · Unique guide id stored in the store | | title | string | 오버레이 상단에 표시할 제목 · Title shown at the top of the card | | match | string | 대상 화면 경로 · Route this guide applies to | | exact | boolean? | true 면 경로가 정확히 일치할 때만 매칭. false/생략 시 match 로 시작하기만 해도 매칭 · Exact route match when true; prefix match otherwise | | steps | GuideStep[] | 가이드 단계 목록 · Ordered list of steps |

GuideStep

| 필드 · Field | Type | 설명 · Description | | ------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | title | string | 단계 제목 (예: 1. 검색창) · Step title | | body | string | 단계 설명 본문 · Step description | | target | string? | 강조할 요소의 CSS 선택자 (예: [data-guide="search-input"]). 없으면 화면 중앙에 카드 표시 · CSS selector to spotlight; centered card when omitted | | placement | GuidePlacement? | 카드 배치 방향. 기본값 auto · Card placement, defaults to auto |

GuidePlacement

type GuidePlacement = "top" | "bottom" | "left" | "right" | "auto";

auto 는 뷰포트에서 공간이 넓은 방향을 골라 배치하고, 지정 방향에 공간이 부족하면 자동으로 반대편으로 뒤집습니다. auto picks the side with the most room; a fixed side flips to the opposite side if it doesn't fit.

경로 매칭 규칙 · Route Matching

• 쿼리스트링·해시·후행 슬래시는 무시됩니다 (/search?q=1 → /search).
• exact: false(기본): match 로 시작하는 하위 경로까지 매칭 (/search 는 /search/detail 도 매칭).
• exact: true: 경로가 정확히 일치할 때만 매칭.
• 여러 가이드가 매칭되면 가장 구체적인(긴) match 가 선택됩니다.

• Query strings, hashes, and trailing slashes are ignored (/search?q=1 → /search).
• exact: false (default): prefix match, so /search also matches /search/detail.
• exact: true: matches only on an exact route.
• When multiple guides match, the most specific (longest) match wins.

라이선스 · License

MIT © SoonMin