@facegate/react

Drop-in face authentication component for React. Add face login in 3 lines of code.

Install

npm install @facegate/react @facegate/client

Quick Start — Supabase App

import { FaceGate } from '@facegate/react'

function LoginPage() {
  return (
    <FaceGate
      apiKey="fg_live_your_key"
      provider="supabase"
      onAuthenticated={(session) => {
        // session.token — FaceGate JWT
        // session.user — { id, name, role }
        // session.provider_session — Supabase access_token + refresh_token
        // Use session.provider_session to set the Supabase client session
      }}
    />
  )
}

That's it. The component handles:

• Camera permission request
• Camera feed display
• Liveness challenge (blink, turn, nod)
• Face verification
• Session creation with Supabase
• QR code fallback if no camera
• Loading, error, and success states

With @facegate/supabase (Recommended)

For full Supabase integration (sets the session automatically):

import { FaceGate } from '@facegate/react'
import { createFaceGateSupabaseClient } from '@facegate/supabase'

const supabase = createFaceGateSupabaseClient({
  supabaseUrl: 'https://your-project.supabase.co',
  supabaseAnonKey: 'your-anon-key',
})

function LoginPage() {
  return (
    <FaceGate
      apiKey="fg_live_your_key"
      provider="supabase"
      onAuthenticated={async (session) => {
        // Sets the Supabase session automatically
        await supabase.auth.setSession({
          access_token: session.provider_session.access_token,
          refresh_token: session.provider_session.refresh_token,
        })
        // Now use supabase client normally — RLS works
        window.location.href = '/dashboard'
      }}
    />
  )
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | string | required | Your FaceGate API key | | onAuthenticated | (session) => void | required | Called on successful auth | | provider | 'supabase' \| 'auth0' \| 'firebase' | none | Auth provider for session creation | | providerConfig | Record<string, unknown> | {} | Provider-specific config | | baseUrl | string | https://api.facegate.io | FaceGate server URL | | confidenceThreshold | number | 95 | Minimum match confidence (0-100) | | challengeTimeout | number | 30000 | Liveness timeout in ms | | autoStart | boolean | true | Auto-start on mount | | className | string | none | Container CSS class | | style | CSSProperties | none | Container inline styles |

Hooks (Custom UI)

Build your own UI using the hooks:

import { useFaceGate, useCamera, useLiveness } from '@facegate/react'

function CustomLogin() {
  const fg = useFaceGate({
    apiKey: 'fg_live_...',
    provider: 'supabase',
    onAuthenticated: (session) => { /* ... */ },
  })

  return (
    <div>
      {fg.mode === 'camera' && <video ref={fg.videoRef} autoPlay playsInline muted />}
      {fg.mode === 'qr' && <img src={fg.qrDataUrl} />}
      {fg.mode === 'success' && <p>Welcome, {fg.session.user.name}</p>}
      {fg.mode === 'error' && <button onClick={fg.retry}>Retry</button>}
    </div>
  )
}

Sub-Components

For partial customization, use individual components:

| Component | Description | |-----------|-------------| | <CameraView> | Video feed + liveness overlay | | <QRView> | QR code display + waiting state | | <LivenessPrompt> | Challenge instruction display | | <PermissionsGate> | Camera permission request UI | | <StatusDisplay> | Loading, success, error states |

Styling

The component uses inline styles by default (no CSS import needed). Override with:

<FaceGate
  className="my-face-gate"
  style={{ maxWidth: '500px', borderRadius: '16px' }}
  apiKey="fg_live_..."
  onAuthenticated={handleAuth}
/>

Browser Support

Works in all modern browsers with camera API support: Chrome, Firefox, Safari, Edge. On devices without cameras, automatically falls back to QR code.