Tuesday, July 1, 2025

PostHog Onboarding Analytics in 5 Minutes (OnboardJS Plugin)

Soma Somorjai

OnboardJS + Posthog for user onboarding analytics

Stop guessing where users drop off in your onboarding. Start seeing it, right now.

This guide will get you live PostHog analytics for your OnboardJS flows in under 5 minutes. No complex configuration, no analytics engineering required. Just plug, play, and see the data.

🤩 Why You Need This (in 60 seconds)

I hate when... I build an onboarding flow, and then I have no idea if it's actually working. Is it too long? Are users getting stuck? Where's the drop-off?

Sound familiar? Most product tours give you pretty UIs, but zero insight into user behavior.

OnboardJS + PostHog = 🔥 Your Secret Weapon.
Get automatic, detailed analytics for every step, every user, every interaction. Identify friction points, track completion rates, and finally understand your user's first journey.

Ready to stop guessing and start optimizing? Let's go.

🚀 Quickstart: Get Analytics LIVE in 5 Minutes!

This example is for a Next.js / React application.

Step 1: Get Your PostHog API Key (1 minute)

Log in to your PostHog account.
Go to Project Settings (gear icon in the sidebar).
Copy your Project API Key.

Step 2: Install the Plugin (30 seconds)

Open your terminal in your Next.js project root and run:

3 lines

npm install @onboardjs/core @onboardjs/react @onboardjs/posthog-plugin posthog-js
# or
yarn add @onboardjs/core @onboardjs/react @onboardjs/posthog-plugin posthog-js

Step 3: Plug it into Your App (3 minutes)

Create the OnboardingProvider if not already defined.

Import the plugin and PostHog.
Initialize PostHog. Refer to the Posthog Docs for Next.js
Instantiate the PostHogPlugin and pass it to your OnboardingProvider.

tsx

48 lines

// src/app/layout.tsx  (for App Router)
// Or src/pages/_app.tsx (for Pages Router)
// Or a separate wrapper component
"use client"; // Make sure this is a Client Component

import { OnboardingProvider } from "@onboardjs/react";
import { createPostHogPlugin } from "@onboardjs/posthog-plugin"; // Import the plugin
import posthog from "posthog-js"; // Import posthog-js

// Define your onboarding steps
const myOnboardingSteps = [
  { id: 'welcome', type: 'INFORMATION', payload: { mainText: 'Hello!' }, nextStep: 'profile' },
  { id: 'profile', type: 'FORM', payload: { /* ... */ }, nextStep: 'complete' },
  { id: 'complete', type: 'CONFIRMATION', payload: { mainText: 'Done!' }, nextStep: null },
];

export default function RootLayout({ children }: { children: React.ReactNode }) {
  // Create the PostHog plugin instance
  // Using createPostHogPlugin is the simplest way!
  const postHogPlugin = createPostHogPlugin({
    posthogInstance: posthog, // Pass the initialized PostHog instance
    debug: process.env.NODE_ENV === 'development', // See logs in console
    // Optional: enable churn detection, milestones etc.
    enableChurnDetection: true,
    churnTimeoutMs: 60000, // Detect abandonment after 60 seconds idle on a step
    enableProgressMilestones: true,
  });

  return (
    <html>
      <body>
        <PostHogProvider client={posthog}>
          <OnboardingProvider 
            steps={myOnboardingSteps} 
            plugins={[postHogPlugin]} // Pass the plugin here!
            initialContext={{ 
              currentUser: { id: 'test-user-1', email: 'test@example.com' },
              flowData: {} 
            }}
            // ... other OnboardingProvider props like localStoragePersistence
          >
            {children}
          </OnboardingProvider>
        </PostHogProvider>
      </body>
    </html>
  );
}

Step 4: See Your Events in PostHog! (1 minute)

Run your Next.js application (npm run dev).
Open your app in the browser and go through a few steps of your onboarding.
Go to your PostHog project.
Navigate to Activity (in the sidebar).

🎉 BOOM! You'll immediately start seeing events like onboarding_flow_started, onboarding_step_active, and onboarding_step_completed hitting your PostHog instance.

🔥 What Just Happened?

You just set up a powerful analytics engine for your onboarding flow with almost zero custom code. The @onboardjs/posthog-plugin is now automatically capturing:

When flows start
Every step view
Every step completion
Step abandonment (if enableChurnDetection is true)
Progress milestones (e.g., 25%, 50% flow completion)
...and much more!

Don't let your onboarding be a black box. Get insights, optimize, and keep your users happy!

This was just a quick guide on how to get started. Check out the full documentation for more details!

➡️ View Full Plugin Documentation
⭐ Star OnboardJS on GitHub

Back to blog