vibecheck/packages/react

@lilithftw/vibecheck-react

React components and hooks for VibeCheck liveness detection. Privacy-first, client-side only.

Installation

bun add @lilithftw/vibecheck-react
# or
npm install @lilithftw/vibecheck-react

Peer Dependencies

• react >= 18.0.0
• react-dom >= 18.0.0

Quick Start

import { VibeCheck } from '@lilithftw/vibecheck-react';

function RegistrationPage() {
  return (
    <VibeCheck
      onSuccess={(result) => {
        console.log('User verified!', result.confidence);
      }}
      onFailure={(error) => {
        console.error('Verification failed:', error);
      }}
    />
  );
}

Components

<VibeCheck />

High-level component with built-in UI for liveness detection.

Prop	Type	Default	Description
onSuccess	(result: LivenessResult) => void	required	Called when liveness check succeeds
onFailure	(error: VibeCheckError) => void	required	Called when check fails or errors
onStatusChange	(status: CheckStatus) => void	—	Called on status transitions
config	LivenessOptions	{}	Detector configuration
theme	'light' | 'dark' | Theme	'light'	UI theme
className	string	—	Custom CSS class
style	React.CSSProperties	—	Custom inline styles
autoStart	boolean	false	Auto-start check on mount
showVideo	boolean	true	Show video preview
instructions	string | React.ReactNode	—	Custom instruction text

Hooks

useVibeCheck(options?)

Headless hook for building custom UI around liveness detection.

const {
  isInitialized,
  isChecking,
  status,      // 'idle' | 'initializing' | 'ready' | 'checking' | 'success' | 'failure' | 'error'
  result,      // LivenessResult | null
  error,       // VibeCheckError | null
  startCheck,  // () => Promise<void>
  reset,       // () => void
  cleanup,     // () => void
} = useVibeCheck({ confidenceThreshold: 0.75 });

useLivenessDetector(options?)

Low-level hook exposing the LivenessDetector instance directly for full control.

const detector = useLivenessDetector({ debug: true });
// Returns LivenessDetector | null

Privacy

All biometric processing happens client-side in the browser. No video, images, or facial data is ever transmitted to servers. Only a boolean result, confidence score, and timestamp cross the network boundary.

See the full Privacy Documentation.

Documentation

• API Reference
• Architecture Overview
• Integration Guide
• Privacy Documentation

License

MIT