Package Exports
- ac-react-onboarding-guide
- ac-react-onboarding-guide/package.json
Readme
Onboarding Guide Component Library
A customizable onboarding guide component for React applications. This library provides a step-by-step onboarding experience that can be easily integrated into any React application.
Features
- Step-by-step onboarding flow
- Responsive design
- Keyboard navigation
- Theming support (light/dark mode)
- Progress tracking
- Skippable steps
- Persistent state (using localStorage)
- Fully accessible (WAI-ARIA compliant)
- Customizable appearance
- TypeScript support
Installation
npm install @acme/onboarding-guide
# or
yarn add @acme/onboarding-guide
# or
pnpm add @acme/onboarding-guidePeer Dependencies
This library requires the following peer dependencies:
{
"react": "^18.0.0 || ^19.0.0",
"react-dom": "^18.0.0 || ^19.0.0",
"tailwindcss": "^3.0.0"
}Usage
Basic Usage
import { OnboardingProvider, OnboardingSidebar } from '@acme/onboarding-guide';
const steps = [
{
id: 'welcome',
title: 'Welcome',
description: 'Get started with our app',
component: <WelcomeStep />,
},
{
id: 'profile',
title: 'Complete Profile',
description: 'Set up your profile',
component: <ProfileStep />,
},
{
id: 'preferences',
title: 'Preferences',
description: 'Configure your preferences',
component: <PreferencesStep />,
},
];
function App() {
return (
<OnboardingProvider steps={steps}>
<div className="flex h-screen">
<OnboardingSidebar />
<main className="flex-1 p-8">
{/* Your app content */}
</main>
</div>
</OnboardingProvider>
);
}With Theme Provider
import { ThemeProvider } from '@acme/onboarding-guide';
function App() {
return (
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
<OnboardingProvider steps={steps}>
{/* Your app */}
</OnboardingProvider>
</ThemeProvider>
);
}Programmatic Control
import { useOnboarding } from '@acme/onboarding-guide';
function MyComponent() {
const {
currentStep,
goToNextStep,
goToPreviousStep,
goToStep,
skipOnboarding,
completeOnboarding,
isFirstStep,
isLastStep,
isCompleted,
isSkipped,
} = useOnboarding();
return (
<div>
<h1>Current Step: {currentStep + 1}</h1>
<button onClick={goToPreviousStep} disabled={isFirstStep}>
Previous
</button>
<button onClick={goToNextStep}>
{isLastStep ? 'Finish' : 'Next'}
</button>
<button onClick={skipOnboarding}>
Skip
</button>
</div>
);
}API Reference
OnboardingProvider
The main provider component that manages the onboarding state.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
steps |
OnboardingStep[] |
[] |
Array of onboarding steps |
initialStep |
number |
0 |
Initial step index |
skipable |
boolean |
true |
Whether the onboarding can be skipped |
storageKey |
string |
'onboarding-steps' |
Key for localStorage |
onComplete |
() => void |
undefined |
Callback when onboarding is completed |
onSkip |
() => void |
undefined |
Callback when onboarding is skipped |
children |
ReactNode |
- | Child components |
OnboardingSidebar
A pre-built sidebar component for the onboarding flow.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
className |
string |
'' |
Additional CSS class names |
showProgress |
boolean |
true |
Show progress bar |
showStepTitles |
boolean |
true |
Show step titles |
showStepIcons |
boolean |
true |
Show step icons |
showNavigation |
boolean |
true |
Show navigation buttons |
showSkipButton |
boolean |
true |
Show skip button |
position |
'left' | 'right' |
'left' |
Position of the sidebar |
width |
number | string |
280 |
Width of the expanded sidebar |
collapsedWidth |
number | string |
80 |
Width of the collapsed sidebar |
defaultCollapsed |
boolean |
false |
Whether the sidebar is collapsed by default |
collapsible |
boolean |
true |
Whether the sidebar can be collapsed |
onCollapseChange |
(collapsed: boolean) => void |
undefined |
Callback when the sidebar is toggled |
useOnboarding
A hook to access the onboarding context.
Return Value
| Property | Type | Description |
|---|---|---|
currentStep |
number |
Current step index |
steps |
OnboardingStep[] |
Array of all steps |
isFirstStep |
boolean |
Whether the current step is the first step |
isLastStep |
boolean |
Whether the current step is the last step |
isCompleted |
boolean |
Whether the onboarding is completed |
isSkipped |
boolean |
Whether the onboarding was skipped |
goToStep |
(step: number) => void |
Go to a specific step |
goToNextStep |
() => Promise<void> |
Go to the next step |
goToPreviousStep |
() => Promise<void> |
Go to the previous step |
skipOnboarding |
() => Promise<void> |
Skip the entire onboarding |
completeOnboarding |
() => void |
Complete the onboarding |
resetOnboarding |
() => void |
Reset the onboarding state |
updateStepStatus |
(stepId: string, status: 'completed' | 'in-progress' | 'pending') => void |
Update the status of a step |
Styling
This library uses Tailwind CSS for styling. Make sure to include Tailwind CSS in your project.
Customization
You can customize the appearance by overriding the default styles using the className prop or by using Tailwind's utility classes.
Accessibility
This library follows WAI-ARIA design patterns and includes proper keyboard navigation and screen reader support.
License
MIT