React Wizard Onboarding

Pretty fancy onboarding wizard for your website, made in React.

Live demo at https://chrisuser.github.io/react-wizard-onboarding.

Installation

Install via npm

npm install --save react-wizard-onboarding

or yarn

yarn add react-wizard-onboarding

Usage

1. Wrap your app inside the <TutorialProvider> context.

Example

const config = createTutorialConfig({
    sticky: true,
    darkMode: true,
    displayDots: true,
    keyboard: true,
    labels: { next: 'Next', back: 'Back', close: 'Close', complete: 'Done' }
})

const Setup: React.FC = () => {
    return (
        <TutorialProvider config={config}>
            <App />
        </TutorialProvider>
    )
}

ReactDOM.createRoot(document.getElementById('root')!).render(<Setup />)

2. Register all the elements of a page to include them into the onboarding carousel.

Example

const { registerTutorialComponent, startTutorial } = useTutorial()
...

return (
    <div className="main-container">
        <header
            ref={registerTutorialComponent({
                position: 1,
                id: 'header',
                tutorialKey: 'main_tutorial',
                text: 'This is the header element...'
            })}
        >
    ...
)

3. Call the startTutorial method from the useTutorial hook anywhere in the page (e.g. with an onClick or useEffect).

Example

<button onClick={() => startTutorial('main_tutorial')}>Start tour</button>

Hooks

• registerTutorialComponent: (componentData: TutorialComponentData) — Registers a component to be highlighted during onboarding. Returns a ref callback.
• startTutorial: (tutorialKey?: string) — Starts the tutorial. Pass a tutorialKey to run only the steps registered under that key. If omitted, all registered components are included.

Keyboard Navigation

When keyboard is enabled (default true), the following keys work while a tour is active:

| Key | Action | | --- | --- | | → / ↓ | Advance to next step | | ← / ↑ | Go back to previous step | | Escape | Close the tour |

Props

TutorialComponentData — connect a component to the onboarding process

| Name | Optional | Type | Description | | --- | --- | --- | --- | | id | | string | Unique component identifier | | position | | number | Step order within the tutorial | | tutorialKey | | string | Groups steps into named tours | | text | ✔️ | string | Step description text | | image | ✔️ | string | Step image URL | | advanceOnClick | ✔️ | boolean | Hides the Next button; the tour advances when the user clicks the highlighted element |

TutorialConfiguration — configure the onboarding wizard UI

| Name | Optional | Type | Description | | --- | --- | --- | --- | | title | ✔️ | string | Wizard title shown in the modal header | | sticky | ✔️ | boolean | Attaches the modal to each highlighted element | | darkMode | ✔️ | boolean | Enables the dark colour theme | | displayDots | ✔️ | boolean | Shows page-dot navigation (non-sticky mode only) | | keyboard | ✔️ | boolean | Enables Arrow-key and Escape keyboard navigation. Defaults to true | | scrollToStep | ✔️ | boolean | Auto-scrolls off-screen target elements into view before showing the spotlight. Defaults to true | | hideArrowOnSticky | ✔️ | boolean | Hides the directional arrow on the sticky modal | | labels | ✔️ | { next?: string; complete?: string; close?: string; back?: string } | Custom button labels | | icons | ✔️ | { next?: ReactNode; complete?: ReactNode; close?: ReactNode; back?: ReactNode } | Custom button icons | | onBeforeStep | ✔️ | (stepIndex: number) => void \| Promise<void> | Async callback fired before entering a step. The tour waits for the promise to resolve | | onAfterStep | ✔️ | (stepIndex: number) => void \| Promise<void> | Async callback fired after leaving a step. The tour waits for the promise to resolve |

Step lifecycle callbacks example

const config = createTutorialConfig({
    sticky: true,
    onBeforeStep: async (index) => {
        // pre-load data, trigger a UI change, log analytics…
        await fetch(`/api/analytics/step/${index}`)
    },
    onAfterStep: async (index) => {
        console.log('Left step', index)
    }
})

advanceOnClick example

registerTutorialComponent({
    position: 3,
    id: 'submit-button',
    tutorialKey: 'main_tutorial',
    text: 'Click this button to continue to the next step.',
    advanceOnClick: true   // Next button is hidden; clicking the element advances the tour
})

License

react-wizard-onboarding is MIT licensed.