facegate-react

@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.