Onboard Engine

A modern, lightweight, and customizable onboarding library for React and Next.js applications.

onboard-engine provides a seamless way to guide users through your application using an animated focus overlay, tooltips, and persistent state management. Built with smooth CSS transitions and Cookies for state persistence.

Features

• Smart Focus Overlay: Dim the background and highlight the target element.
• Deeply Customizable: Custom renderers for buttons and styling options for the overlay.
• State Persistence: Remembers the user's progress across page reloads using cookies.
• Automatic Navigation: Seamlessly transitions between steps on different pages.
• Interactive: Supports click automation and draggable tooltips.
• SSR Compatible: Built with Server-Side Rendering (Next.js) in mind.

Installation

npm install onboard-engine
# or
yarn add onboard-engine
# or
pnpm add onboard-engine
# or
bun add onboard-engine

Getting Started

1. Import Styles

Important: You must import the CSS for the overlay and tooltip to render correctly.

Import the necessary CSS in your global stylesheet or root component (e.g., _app.tsx or layout.tsx).

import 'onboard-engine/dist/index.css';

2. Define Configuration

Create your onboarding configuration object. This defines the steps, metadata, and optional styling.

import { OnboardingConfig } from 'onboard-engine';

const onboardingConfig: OnboardingConfig = {
  metadata: {
    name: 'user-onboarding',
    draggable: true,
    inOrder: true,
    simulateClicksOnNavigate: true, // Re-activates parent clicks (like opening a modal) on page refresh
  },
  steps: [
    {
      title: 'Welcome!',
      description: 'Let us show you around the dashboard.',
      attribute: 'welcome-header',
      urlMatch: '/',
      urlBase: '/',
      navigate: '/home',
    },
    {
      title: 'Create Project',
      description: 'Click here to start a new project.',
      attribute: 'create-btn',
      urlMatch: '/home',
      urlBase: '/home',
      navigate: '/dashboard',
      click: true, // Clicks the button automatically when moving to the next step
      subSteps: [
        {
          title: 'Project Name',
          description: 'Enter a unique name for your project.',
          attribute: 'project-name-input',
        },
      ],
    },
  ],
  onOnboardingComplete: () => {
    console.log('Onboarding finished!');
  },
};

3. Wrap Your Application

Wrap your application (or the part you want to onboard) with the OnboardingProvider.

import { OnboardingProvider } from 'onboard-engine';

export default function App({ children }) {
  return (
    <OnboardingProvider
      config={onboardingConfig}
      onNavigate={(url) => console.log('Navigating to', url)}
    >
      {children}
    </OnboardingProvider>
  );
}

4. Tag Your Elements

Add the data-onboarding-id attribute to the elements you want to highlight. This must match the attribute defined in your config steps.

<h1 data-onboarding-id="welcome-header">Welcome to My App</h1>
<button data-onboarding-id="create-btn">Create Project</button>
<input data-onboarding-id="project-name-input" type="text" />

API Reference

OnboardingProvider Props

| Property | Type | Description | | :----------- | :---------------------- | :---------------------------------------------------------------------------------- | | config | OnboardingConfig | Required. The configuration object for the onboarding flow. | | ssr | boolean | Optional. Set to true if using Server-Side Rendering. | | onNavigate | (url: string) => void | Optional. Custom navigation handler (e.g. for next/navigation or react-router). |

OnboardingMetadata

| Property | Type | Default | Description | | :------------------------- | :-------- | :------- | :-------------------------------------------------------------------------------------------- | | name | string | Required | Unique name for the onboarding flow. | | nextRouter | boolean | false | Enable if using Next.js router. | | draggable | boolean | false | Allow the tooltip to be dragged. | | inOrder | boolean | true | If true, strict step order is enforced. If false, matching urlMatch activates the step. | | simulateClicksOnNavigate | boolean | false | If true, re-triggers the parent step's click when resuming in a sub-step after a refresh. |

OnboardingStep

| Property | Type | Description | | :------------ | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | title | string | Title displayed in the tooltip. | | description | string | Description text in the tooltip. | | attribute | string | The data-onboarding-id value to target. | | urlMatch | string | RegExp | Required. Checks if current URL matches to active this step. Supports * wildcards in strings (e.g., "/user/*"). Note: RegExp objects cannot be passed from Server Components in Next.js. Use string wildcards or define config in a Client Component. | | urlBase | string | Required. The base URL for this step. If inOrder is true, the user will be navigated here if they are on a non-matching page. | | navigate | string | URL to navigate to when this step is completed (next button clicked). | | click | boolean | If true, clicks the element when the step activates. | | subSteps | OnboardingSubStep[] | Nested steps for complex workflows. |

Hooks

useOnboarding()

Access the onboarding state and controls from any component within the provider.

import { useOnboarding } from 'onboard-engine';

const MyComponent = () => {
  const {
    nextStep,
    prevStep,
    finish,
    goToStep,
    state,
    currentStep,
    isFirstStep,
    isLastStep,
    config,
  } = useOnboarding();

  return <button onClick={nextStep}>Next</button>;
};

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC © Forsrobin