OnboardJS

OnboardJS vs Intro.js

Intro.js Alternative: Why Devs Switch to OnboardJS

Intro.js pioneered product tours, but its jQuery-era architecture shows its age. If you're building with React, Next.js, or any modern framework, OnboardJS gives you a native experience.

At a Glance

Feature Comparison

FeatureIntro.jsOnboardJS
ArchitectureDOM manipulationHeadless/native
Step TypesTooltips onlyModals, tooltips, inline, custom
TypeScriptCommunity typesNative TypeScript
AnalyticsNoneBuilt-in tracking
Design SystemFixed CSS themesYour components (Tailwind/Shadcn)
MaintenanceLegacy codebaseModern React patterns

Why Switch?

The Architectural Differences

Why Intro.js Doesn't Fit Modern React

Intro.js manipulates the DOM directly, fighting against React's virtual DOM. This creates race conditions, stale references, and hydration mismatches in SSR apps.

Intro.js

introJs().start() runs outside React lifecycle, causing ref issues

OnboardJS

OnboardJS is a React hook—it respects component lifecycle and state

The Styling Prison

Intro.js comes with its own CSS that you must override. Want to use Tailwind? You'll be writing !important rules. Want Shadcn components? Not possible.

Intro.js

introjs.css must be imported and heavily overridden

OnboardJS

No CSS required—render your own Tailwind-styled components

No State Management Integration

Intro.js has no concept of React state. Persisting progress, conditional steps, or integrating with your app's state management requires complex workarounds.

Intro.js

Manual localStorage calls to save progress

OnboardJS

Built-in persistence, or bring your own state adapter

Migration

Before & After

See the difference in code. OnboardJS lets you use your own components while keeping the API simple.

BeforeIntro.js: DOM manipulation, external CSS
tsx
24 lines
import introJs from 'intro.js';
import 'intro.js/introjs.css';

function App() {
  useEffect(() => {
    introJs()
      .setOptions({
        steps: [
          {
            element: document.querySelector('.step-1'),
            intro: 'Welcome to the app!',
          },
        ],
        showProgress: true,
        showBullets: false,
      })
      .oncomplete(() => {
        localStorage.setItem('tour_complete', 'true');
      })
      .start();
  }, []);

  return <div className="step-1">...</div>;
}
AfterOnboardJS: React-native, automatic persistence
tsx
23 lines
import { OnboardingProvider, useOnboarding } from '@onboardjs/react';

const steps = [
  {
    id: 'welcome',
    component: () => (
      <Card className="p-4">  {/* Your Shadcn Card */}
        <h3>Welcome to the app!</h3>
      </Card>
    ),
  },
];

function App() {
  return (
    <OnboardingProvider
      steps={steps}
      persist={{ key: 'onboarding', storage: 'localStorage' }}
    >
      <YourApp />
    </OnboardingProvider>
  );
}

Ready to drop the overlays?

Start building onboarding that feels native to your app.

Terminal
1 lines
npm install @onboardjs/core @onboardjs/react
View on GitHub