@dial8/onboard

A powerful, flexible React onboarding and authentication library with swappable templates and backend adapters.

Features

• 🔧 Pluggable Architecture - Swap templates and auth adapters easily
• 🎨 Customizable UI - Built-in themes and brand customization
• 🔐 Multiple Auth Providers - Firebase, custom backends, and more
• 📱 Responsive Design - Works on all devices
• 🎯 TypeScript Ready - Full TypeScript support
• ⚡ React 18 & 19 - Compatible with latest React versions

Installation

npm install @dial8/onboard

Quick Start

import { OnboardingFlow } from "@dial8/onboard";
import { MinimalTemplate } from "@dial8/onboard-template-minimal";
import { firebaseAdapter } from "@dial8/onboard-adapter-firebase";

function App() {
  return (
    <OnboardingFlow
      template={MinimalTemplate}
      adapter={firebaseAdapter({
        apiKey: "your-api-key",
        authDomain: "your-project.firebaseapp.com",
        projectId: "your-project-id",
      })}
      steps={["signInOrUp", "verifyEmail", "profile", "success"]}
      theme={{ brandColor: "#0ea5e9", darkMode: false }}
      brand={{ 
        title: "Welcome to MyApp", 
        subtitle: "Get started in seconds",
        logo: "/logo.png" 
      }}
    />
  );
}

Components

OnboardingFlow

The main component that orchestrates the entire onboarding experience.

<OnboardingFlow
  template={YourTemplate}
  adapter={yourAdapter}
  steps={["signInOrUp", "profile", "success"]}
  theme={{ brandColor: "#0ea5e9" }}
  brand={{ title: "Welcome" }}
  onComplete={(user) => console.log('User completed onboarding:', user)}
  onError={(error) => console.log('Error:', error)}
/>

Props

• template - Template component for rendering UI
• adapter - Authentication adapter
• steps - Array of onboarding steps
• theme - Theme configuration
• brand - Brand/logo configuration
• onComplete? - Callback when onboarding completes
• onError? - Callback when errors occur

Built-in Steps

• signInOrUp - Email/password authentication
• verifyEmail - Email verification step
• profile - Profile completion
• success - Success/completion page

Theming

const theme = {
  brandColor: "#0ea5e9",
  darkMode: true,
  // Add more theme options as needed
};

Branding

const brand = {
  title: "Welcome to MyApp",
  subtitle: "Get started with your account",
  logo: "/path/to/logo.png"
};

Auth Context

Use the auth context to access user state throughout your app:

import { AuthProvider, useAuth } from "@dial8/onboard";

function App() {
  return (
    <AuthProvider adapter={yourAdapter}>
      <YourAppContent />
    </AuthProvider>
  );
}

function YourAppContent() {
  const { user, signOut, isLoading } = useAuth();
  
  if (isLoading) return <div>Loading...</div>;
  if (!user) return <OnboardingFlow ... />;
  
  return (
    <div>
      Welcome {user.email}!
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}

TypeScript

Full TypeScript support with exported types:

import type { 
  User, 
  AuthAdapter, 
  TemplateProps, 
  OnboardingStep 
} from "@dial8/onboard";

Related Packages

• @dial8/onboard-template-minimal - Clean, minimal template
• @dial8/onboard-adapter-firebase - Firebase authentication adapter

Creating Custom Adapters

import { AuthAdapter, User } from '@dial8/onboard';

export function myAdapter(config): AuthAdapter {
  return {
    async getSession(): Promise<User | null> {
      // Return current user or null
    },
    async signInEmailPassword(email, password): Promise<User> {
      // Implement sign in
    },
    async signUpEmailPassword(email, password): Promise<User> {
      // Implement sign up  
    },
    async signOut(): Promise<void> {
      // Implement sign out
    },
    onAuthStateChanged(callback): () => void {
      // Set up auth state listener
      // Return unsubscribe function
    }
  };
}

Creating Custom Templates

import { TemplateProps } from '@dial8/onboard';

export function MyTemplate({ 
  step, ui, brand, theme, onNext, onSubmit 
}: TemplateProps) {
  switch (step) {
    case 'signInOrUp':
      return <MySignInForm onSubmit={onSubmit} />;
    case 'profile':
      return <MyProfileForm onSubmit={onSubmit} />;
    default:
      return <div>Step: {step}</div>;
  }
}

License

MIT

Support

• GitHub Issues
• Documentation