https://github.com/chrisuser/react-wizard-onboarding
Pretty fancy onboarding wizard, for your webapp or your website, made in React.
https://github.com/chrisuser/react-wizard-onboarding
onboarding react walkthrough wizard wizard-steps
Last synced: 2 months ago
JSON representation
Pretty fancy onboarding wizard, for your webapp or your website, made in React.
- Host: GitHub
- URL: https://github.com/chrisuser/react-wizard-onboarding
- Owner: ChrisUser
- License: mit
- Created: 2023-09-01T20:30:04.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-01-17T09:30:31.000Z (over 1 year ago)
- Last Synced: 2026-02-06T20:45:02.508Z (4 months ago)
- Topics: onboarding, react, walkthrough, wizard, wizard-steps
- Language: TypeScript
- Homepage: https://chrisuser.github.io/react-wizard-onboarding/
- Size: 652 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# React Wizard Onboarding
Pretty fancy onboarding wizard for your website, made in React.
Live **demo** at [https://chrisuser.github.io/react-wizard-onboarding](https://chrisuser.github.io/react-wizard-onboarding/).
# Installation
Install via npm
```sh
npm install --save react-wizard-onboarding
```
or yarn
```sh
yarn add react-wizard-onboarding
```
# Usage
1. Wrap your app inside the `` context.
### Example
```typescript
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 (
)
}
ReactDOM.createRoot(document.getElementById('root')!).render()
```
2. Register all the elements of a page to include them into the onboarding carousel.
### Example
```typescript
const { registerTutorialComponent, startTutorial } = useTutorial()
...
return (
...
)
```
3. Call the `startTutorial` method from the `useTutorial` hook anywhere in the page (e.g. with an `onClick` or `useEffect`).
### Example
```tsx
startTutorial('main_tutorial')}>Start tour
```
# 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` | Async callback fired before entering a step. The tour waits for the promise to resolve |
| onAfterStep | ✔️ | `(stepIndex: number) => void \| Promise` | Async callback fired after leaving a step. The tour waits for the promise to resolve |
### Step lifecycle callbacks example
```typescript
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
```typescript
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.