@zalt/react

React hooks and components for Zalt.io authentication. Beautiful, accessible, customizable.

Installation

npm install @zalt/core @zalt/react

Quick Start

import { ZaltProvider, useAuth, SignedIn, SignedOut, UserButton } from '@zalt/react';

function App() {
  return (
    <ZaltProvider realmId="your-realm-id">
      <Header />
      <MainContent />
    </ZaltProvider>
  );
}

function Header() {
  return (
    <header>
      <SignedIn>
        <UserButton />
      </SignedIn>
      <SignedOut>
        <a href="/sign-in">Sign In</a>
      </SignedOut>
    </header>
  );
}

Features

• 🎣 React Hooks - useAuth, useUser, useMFA, useZaltClient
• 🧩 Components - SignedIn, SignedOut, UserButton, SignInButton
• 🎨 Theming - CSS variables, dark mode, customizable
• ♿ Accessible - WCAG 2.1 AA compliant
• 📦 Lightweight - < 3KB gzipped

API Reference

ZaltProvider

Wrap your app with ZaltProvider to enable authentication.

<ZaltProvider
  realmId="your-realm-id"
  apiUrl="https://api.zalt.io"  // Optional
  appearance={{                  // Optional theming
    theme: 'auto',              // 'light' | 'dark' | 'auto'
    variables: {
      colorPrimary: '#0066ff',
      borderRadius: '8px',
    },
  }}
>
  {children}
</ZaltProvider>

useAuth

Main authentication hook.

function Component() {
  const {
    user,              // Current user or null
    isLoading,         // Loading state
    isAuthenticated,   // Boolean
    signIn,            // (email, password) => Promise
    signUp,            // (email, password, profile?) => Promise
    signOut,           // () => Promise
  } = useAuth();

  const handleLogin = async () => {
    const result = await signIn('[email protected]', 'password');
    if (result.mfaRequired) {
      // Redirect to MFA page
    }
  };
}

useUser

Get current user data.

function Profile() {
  const { user, isLoading } = useUser();

  if (isLoading) return <Spinner />;
  if (!user) return <div>Not logged in</div>;

  return <div>Hello, {user.email}</div>;
}

useMFA

MFA setup and verification.

function MFASetup() {
  const { 
    setup,      // (method: 'totp' | 'webauthn') => Promise
    verify,     // (code: string) => Promise
    isLoading,
    qrCode,     // QR code data URL after setup
    backupCodes // Array of backup codes
  } = useMFA();

  return (
    <button onClick={() => setup('totp')}>
      Enable 2FA
    </button>
  );
}

useZaltClient

Access the raw ZaltClient for advanced use cases.

function Advanced() {
  const client = useZaltClient();
  
  // Direct API access
  await client.webauthn.register({ name: 'My Device' });
}

SignedIn / SignedOut

Conditional rendering based on auth state.

<SignedIn>
  <p>Welcome back!</p>
  <UserButton />
</SignedIn>

<SignedOut>
  <p>Please sign in</p>
  <SignInButton />
</SignedOut>

UserButton

User avatar with dropdown menu.

<UserButton 
  afterSignOutUrl="/"
  showName={true}
/>

SignInButton / SignUpButton

Pre-styled auth buttons.

<SignInButton mode="modal" />
<SignUpButton redirectUrl="/onboarding" />

Theming

Customize appearance with CSS variables:

<ZaltProvider
  realmId="your-realm-id"
  appearance={{
    theme: 'dark',
    variables: {
      colorPrimary: '#6366f1',
      colorBackground: '#1a1a2e',
      colorText: '#ffffff',
      fontFamily: 'Inter, sans-serif',
      borderRadius: '12px',
    },
  }}
>

Or use CSS:

:root {
  --zalt-color-primary: #6366f1;
  --zalt-color-background: #ffffff;
  --zalt-border-radius: 8px;
}

TypeScript

Full TypeScript support with exported types:

import type { User, AuthResult, ZaltConfig } from '@zalt/react';

License

MIT