Skip to main content

​
Overview

The useOnboardingTracker hook creates an OnboardingTracker instance that helps track user progress through onboarding flows. It provides methods for starting, completing, skipping steps, and monitoring overall progress.

​
Usage

import { useOnboardingTracker } from 'mentiq-sdk';
import { useAnalytics } from 'mentiq-sdk';

function OnboardingFlow() {
  const { analytics } = useAnalytics();
  const tracker = useOnboardingTracker(analytics, {
    steps: [
      { name: 'create_account', index: 0, required: true },
      { name: 'add_profile', index: 1, required: true },
      { name: 'invite_team', index: 2, required: false },
      { name: 'complete_tutorial', index: 3, required: false }
    ]
  });

  const handleStepComplete = (stepName: string) => {
    tracker?.completeStep(stepName, { timestamp: Date.now() });
  };

  return (
    <div>
      <button onClick={() => tracker?.start()}>Start Onboarding</button>
      <button onClick={() => handleStepComplete('create_account')}>
        Complete Account Creation
      </button>
    </div>
  );
}

​
Parameters

​
analytics
Analytics | null
required
The analytics instance from useAnalytics(). Returns null if analytics is not available.
​
config
OnboardingConfig
required
Configuration object for the onboarding flow
​
config.steps
OnboardingStep[]
required
Array of onboarding stepsEach step has:
  • name (string): Unique identifier for the step
  • index (number): Order of the step (0-based)
  • required (boolean, optional): Whether step is required for completion
​
config.autoTrack
boolean
Whether to automatically track step progression (not currently implemented)

​
Returns

​
OnboardingTracker | null
object
Returns an OnboardingTracker instance with the following methods, or null if analytics is unavailable.

​
Methods

​
start()

Start the onboarding process and track the “onboarding_started” event. Signature: start(properties?: Record<string, any>): void 
tracker?.start({
  source: 'signup_page',
  user_type: 'free_trial'
});
Tracked Event: "onboarding_started"
  • total_steps: Number of steps in the flow
  • Any additional properties passed

​
completeStep()

Mark a step as completed and track progress. Signature: completeStep(stepName: string, properties?: Record<string, any>): void 
tracker?.completeStep('create_account', {
  account_type: 'business',
  signup_method: 'google'
});
Tracked Event: "onboarding_step_completed"
  • step_name: Name of the completed step
  • step_index: Index of the step
  • required: Whether the step was required
  • steps_completed: Total steps completed so far
  • total_steps: Total steps in the flow
  • progress: Completion percentage (0-100)
  • time_since_start: Milliseconds since onboarding started
  • Any additional properties passed

​
skipStep()

Skip an optional step (only works for non-required steps). Signature: skipStep(stepName: string, reason?: string): void 
tracker?.skipStep('invite_team', 'will_do_later');
Tracked Event: "onboarding_step_skipped"
  • step_name: Name of the skipped step
  • step_index: Index of the step
  • reason: Reason for skipping (defaults to “not_specified”)
  • steps_completed: Steps completed so far
  • total_steps: Total steps in the flow
Attempting to skip a required step will log a warning and not track the event.

​
complete()

Mark the entire onboarding flow as complete. Signature: complete(properties?: Record<string, any>): void 
tracker?.complete({
  completion_quality: 'full',
  features_enabled: ['analytics', 'alerts']
});
Tracked Event: "onboarding_completed"
  • steps_completed: Total steps completed
  • total_steps: Total steps in the flow
  • completion_rate: Percentage of steps completed (0-100)
  • duration_ms: Total time in milliseconds
  • duration_seconds: Total time in seconds
  • Any additional properties passed

​
abandon()

Mark onboarding as abandoned and track where the user dropped off. Signature: abandon(reason?: string): void 
tracker?.abandon('too_complex');
Tracked Event: "onboarding_abandoned"
  • step_name: Current step where user abandoned
  • step_index: Index of current step
  • steps_completed: Steps completed before abandoning
  • total_steps: Total steps in flow
  • progress: Completion percentage when abandoned
  • duration_ms: Time spent before abandoning
  • reason: Reason for abandoning (defaults to “not_specified”)

​
getProgress()

Get current onboarding progress. Signature: getProgress(): ProgressObject 
const progress = tracker?.getProgress();
console.log(`${progress?.progressPercent}% complete`);
Returns: 
{
  currentStep: string | null;         // Current step name
  currentStepIndex: number;           // Current step index
  completedSteps: string[];           // Array of completed step names
  totalSteps: number;                 // Total number of steps
  progressPercent: number;            // Completion percentage (0-100)
  duration: number | null;            // Time elapsed in ms, or null if not started
}

​
isStepCompleted()

Check if a specific step has been completed. Signature: isStepCompleted(stepName: string): boolean 
if (tracker?.isStepCompleted('create_account')) {
  // Show next step
}

​
reset()

Reset the tracker to initial state. Signature: reset(): void 
tracker?.reset(); // Clear all progress

​
Type Definitions

​
OnboardingConfig

interface OnboardingConfig {
  steps: OnboardingStep[];
  autoTrack?: boolean;
}

​
OnboardingStep

interface OnboardingStep {
  name: string;
  index: number;
  required?: boolean;
}

​
Examples

​
Multi-Step Wizard

import { useOnboardingTracker } from 'mentiq-sdk';
import { useAnalytics } from 'mentiq-sdk';
import { useState } from 'react';

function OnboardingWizard() {
  const { analytics } = useAnalytics();
  const [currentStep, setCurrentStep] = useState(0);
  
  const tracker = useOnboardingTracker(analytics, {
    steps: [
      { name: 'welcome', index: 0, required: true },
      { name: 'profile', index: 1, required: true },
      { name: 'preferences', index: 2, required: false },
      { name: 'finish', index: 3, required: true }
    ]
  });

  const handleNext = () => {
    const stepName = tracker?.getProgress().currentStep;
    if (stepName) {
      tracker?.completeStep(stepName);
    }
    setCurrentStep(prev => prev + 1);
  };

  const handleSkip = () => {
    const stepName = tracker?.getProgress().currentStep;
    if (stepName) {
      tracker?.skipStep(stepName, 'user_skipped');
    }
    setCurrentStep(prev => prev + 1);
  };

  React.useEffect(() => {
    if (currentStep === 0) {
      tracker?.start({ source: 'app_launch' });
    }
  }, [tracker]);

  return (
    <div>
      <StepContent step={currentStep} />
      <button onClick={handleNext}>Next</button>
      <button onClick={handleSkip}>Skip</button>
    </div>
  );
}

​
Progress Bar Display

import { useOnboardingTracker } from 'mentiq-sdk';
import { useAnalytics } from 'mentiq-sdk';

function OnboardingProgress() {
  const { analytics } = useAnalytics();
  const tracker = useOnboardingTracker(analytics, config);
  const progress = tracker?.getProgress();

  return (
    <div>
      <div className="progress-bar">
        <div 
          className="progress-fill" 
          style={{ width: `${progress?.progressPercent || 0}%` }}
        />
      </div>
      <p>
        Step {(progress?.currentStepIndex || 0) + 1} of {progress?.totalSteps}
      </p>
      <p>{progress?.progressPercent.toFixed(0)}% Complete</p>
    </div>
  );
}

​
Conditional Step Logic

import { useOnboardingTracker } from 'mentiq-sdk';
import { useAnalytics } from 'mentiq-sdk';

function SmartOnboarding() {
  const { analytics } = useAnalytics();
  const tracker = useOnboardingTracker(analytics, config);

  const handleUserAction = (action: string) => {
    if (action === 'upgrade_to_premium') {
      // Skip free tier onboarding steps
      tracker?.skipStep('free_trial_intro', 'upgraded_to_premium');
      tracker?.completeStep('select_premium_plan');
    }
  };

  return (
    <div>
      {!tracker?.isStepCompleted('select_plan') && (
        <PlanSelection onSelect={handleUserAction} />
      )}
    </div>
  );
}

​
Automatic Completion

When all steps are completed (via completeStep()), the tracker automatically calls complete() to track the “onboarding_completed” event.

​
Notes

Track granular step completion to understand where users drop off in your onboarding flow. Use the abandon() method to explicitly track when users exit the flow.
Required steps cannot be skipped. Attempting to skip a required step will log a console warning and no event will be tracked.
The tracker maintains state in memory. If you need persistence across page refreshes, store progress in localStorage or your backend.

Build docs developers (and LLMs) love

Get started for freeTalk to us