Skip to main content
This guide details steps to install Onboarding SDK 3, mount the embedded onboarding runtime into your page, and handle its lifecycle callbacks.

​
Prerequisites

Before you start, ensure that you have:
  • A valid invite token for the customer or applicant who is to be onboarded
  • Node.js and npm installed in your project
1

Install the SDK

Install the SDK package via npm:
npm install @worthai/onboarding-sdk
2

Add a mount target

Add an empty element to your page wherein the onboarding flow should render. SDK 3 mounts directly into this element
<div id="worth-onboarding"></div>
3

Create the onboarding instance

Call createWorthOnboarding with your invite token and lifecycle callbacks:
import { createWorthOnboarding } from '@worthai/onboarding-sdk';

const onboarding = createWorthOnboarding({
  inviteToken: '{{YOUR_INVITE_TOKEN}}',
  onStepSubmit: ({ inviteToken, stepId, values }) => {
    // Called each time an onboarding step is submitted
    console.log('Step submitted:', stepId, values);
  },
  onComplete: ({ inviteToken, values }) => {
    // Called when the applicant finishes the onboarding flow
    console.log('Onboarding completed:', values);
  },
  onError: (error) => {
    // Called on SDK or runtime errors
    console.error('Onboarding error:', error);
  },
});
Use apiBaseUrl only if you’re targeting a non-production or non-default Worth API environment:
const onboarding = createWorthOnboarding({
  apiBaseUrl: 'https://api.staging.example.com',
  inviteToken: '{{YOUR_INVITE_TOKEN}}',
  onComplete: ({ values }) => {},
  onStepSubmit: ({ stepId, values }) => {},
  onError: (error) => {},
});
4

Mount the SDK

mount() is asynchronous and accepts either a CSS selector string or an HTMLElement. It resolves once the onboarding flow has rendered into the target
await onboarding.mount('#worth-onboarding');
Because mount() returns a promise, wrap it in a try/catch if you want to handle mount-time failures separately from runtime errors reported through onError
try {
  await onboarding.mount('#worth-onboarding');
} catch (error) {
  console.error('Failed to mount onboarding:', error);
}
5

Clean up on unmount

Call unmount() when the containing route or component unloads. SDK 3 supports only one mounted instance at a time, so unmounting is required before mounting a new instance on the same page
onboarding.unmount();

​
Putting It Together

import { createWorthOnboarding } from '@worthai/onboarding-sdk';

const onboarding = createWorthOnboarding({
  inviteToken: '{{YOUR_INVITE_TOKEN}}',
  onStepSubmit: ({ stepId, values }) => {
    console.log('Step submitted:', stepId, values);
  },
  onComplete: ({ values }) => {
    console.log('Onboarding completed:', values);
  },
  onError: (error) => {
    console.error('Onboarding error:', error);
  },
});

try {
  await onboarding.mount('#worth-onboarding');
} catch (error) {
  console.error('Failed to mount onboarding:', error);
}

// Later, on route change or component teardown:
// onboarding.unmount();

<!-- In your HTML: -->
<div id="worth-onboarding"></div>

​
Using SDK 3 in a Framework

The example above is illustrative vanilla TypeScript. In component-based frameworks like React, create the instance once, mount it when the component mounts, and unmount it in your cleanup function: 
import { useEffect, useRef } from 'react';
import { createWorthOnboarding, type WorthOnboarding } from '@worthai/onboarding-sdk';

function OnboardingFlow({ inviteToken }: { inviteToken: string }) {
  const mountRef = useRef<HTMLDivElement>(null);
  const onboardingRef = useRef<WorthOnboarding | null>(null);

  useEffect(() => {
    if (!mountRef.current) return;

    const onboarding = createWorthOnboarding({
      inviteToken,
      onComplete: ({ values }) => console.log('Onboarding completed:', values),
      onError: (error) => console.error('Onboarding error:', error),
    });

    onboardingRef.current = onboarding;
    onboarding.mount(mountRef.current).catch((error) => {
      console.error('Failed to mount onboarding:', error);
    });

    return () => {
      onboarding.unmount();
      onboardingRef.current = null;
    };
  }, [inviteToken]);

  return <div ref={mountRef} />;
}

​
Content Security Policy

SDK 3 injects its scoped runtime styles automatically during mount(). If your host page enforces a strict style-src Content Security Policy, pass your page’s request-level nonce with styleNonce: 
const onboarding = createWorthOnboarding({
  inviteToken: '{{YOUR_INVITE_TOKEN}}',
  styleNonce: window.__CSP_NONCE__,
  onComplete: ({ values }) => {},
});

​
Handling Errors

onError receives a WorthOnboardingError, which includes a code that you can branch on. See Error Handling for a complete list of error codes. 
import { isWorthOnboardingError } from '@worthai/onboarding-sdk';

onError: (error) => {
  if (isWorthOnboardingError(error)) {
    console.error(`[${error.code}] ${error.message}`);
  } else {
    console.error(error);
  }
};

​
Next Steps

​
Support

For questions or issues, please contact your Worth Customer Success team or reach out to support@joinworth.com.