Pretty fancy onboarding wizard for your website, made in React.
Live demo at https://chrisuser.github.io/react-wizard-onboarding.
Install via npm
npm install --save react-wizard-onboardingor yarn
yarn add react-wizard-onboarding- Wrap your app inside the
<TutorialProvider>context.
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 />)- Register all the elements of a page to include them into the onboarding carousel.
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...'
})}
>
...
)- Call the
startTutorialmethod from theuseTutorialhook anywhere in the page (e.g. with anonClickoruseEffect).
<button onClick={() => startTutorial('main_tutorial')}>Start tour</button>registerTutorialComponent: (componentData: TutorialComponentData)— Registers a component to be highlighted during onboarding. Returns a ref callback.startTutorial: (tutorialKey?: string)— Starts the tutorial. Pass atutorialKeyto run only the steps registered under that key. If omitted, all registered components are included.
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 |
| 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 |
| 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 |
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)
}
})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
})react-wizard-onboarding is MIT licensed.