React

Integrate the Circadify Web SDK into your React application with the built-in React bindings.

This guide walks you through integrating Circadify into a React application using the React bindings that ship with the Web SDK.

The React components and hooks ship inside @circadify/web-sdk at the @circadify/web-sdk/react subpath — there is no separate package to install. Follow the Web SDK installation guide to get GitHub Packages access and run npm install @circadify/web-sdk; that single install gives you both the headless SDK and the React bindings.

Styles

The React bindings ship an opt-in stylesheet for the bundled views (Readiness, Scan, Results). Import it once -- typically alongside your global CSS or in your app entry point:

import '@circadify/web-sdk/react/styles.css';

Without this import the components render unstyled. If you build a fully custom UI with the hooks only (never mounting <CircadifyScan> or the composable views), the stylesheet is optional.

Provider Setup

Wrap your application (or the relevant subtree) with the CircadifyProvider. This initializes the SDK and makes it available to all child components via React context.

import { CircadifyProvider } from '@circadify/web-sdk/react';
 
function App() {
  return (
    <CircadifyProvider apiKey="ck_live_your_key_here">
      <YourApp />
    </CircadifyProvider>
  );
}

Provider Props

Using the Component

The CircadifyScan component renders a complete scanning interface with a camera feed, face guide overlay, progress indicator, and quality warnings. It handles the full session lifecycle automatically.

import { CircadifyScan } from '@circadify/web-sdk/react';
 
function ScanPage() {
  const handleResult = (result) => {
    console.log('Heart Rate:', result.heartRate);
    console.log('Confidence:', result.confidence);
  };
 
  return (
    <CircadifyScan
      type="standard"
      onResult={handleResult}
      onError={(error) => console.error(error)}
    />
  );
}

Component Props

Handling Results

The onResult callback receives a VitalSignsResult object:

function ScanPage() {
  const [vitals, setVitals] = useState(null);
 
  return (
    <>
      <CircadifyScan
        type="standard"
        demographics={{ age: 35, sex: 'M' }}
        onResult={(result) => setVitals(result)}
        onError={(error) => alert(error.message)}
      />
      {vitals && (
        <div>
          <p>Heart Rate: {vitals.heartRate} BPM</p>
          <p>SpO2: {vitals.spo2}%</p>
          <p>Confidence: {(vitals.confidence * 100).toFixed(0)}%</p>
        </div>
      )}
    </>
  );
}

Composable Subcomponents

When the all-in-one <CircadifyScan> doesn't fit -- for example, you want a custom view between Readiness and Results, or you want to render Results inside a modal -- import the underlying views and pair them with useSession() (or your own state).

Each subcomponent is presentational and props-driven; none of them own SDK lifecycle.

import {
  CircadifyProvider,
  CircadifyReadiness,
  CircadifyResults,
  useSession,
  useCamera,
} from '@circadify/web-sdk/react';
import { useRef } from 'react';
import '@circadify/web-sdk/react/styles.css';
 
function CustomFlow() {
  const session = useSession();
  const videoRef = useRef(null);
  const camera = useCamera({ videoRef });
 
  if (session.result) {
    return <CircadifyResults result={session.result} onRescan={() => session.start()} />;
  }
  return (
    <CircadifyReadiness
      videoRef={videoRef}
      landmarks={null}        /* leave null unless you render a custom overlay — prefer CircadifyScanView or a 2D canvas, not a hand-rolled r3f overlay */
      quality={null}
      cameraStatus={camera.status}
      cameraError={camera.error}
      onStart={() => session.start({ videoElement: videoRef.current })}
    />
  );
}

Using Hooks

For more control over the scanning lifecycle, use the SDK hooks directly. This is useful when you need a custom UI or want to integrate scanning into an existing component.

useCircadify()

Returns the underlying CircadifySDK instance from the nearest CircadifyProvider. Use this for direct SDK access.

import { useCircadify } from '@circadify/web-sdk/react';
 
function DebugPanel() {
  const sdk = useCircadify();
  // Access sdk.measureVitals(), sdk.destroy(), sdk.cancel(), sdk.getDeviceCapabilities(), etc.
}

useSession(options)

Manages a scan session with start/stop controls and reactive state. Returns the session state, control functions, and result data.

import { useCircadify, useSession } from '@circadify/web-sdk/react';
 
function CustomScan() {
  const client = useCircadify();
  const { session, start, stop, result, error, progress, isScanning } = useSession({
    type: 'standard',
  });
 
  return (
    <div>
      <button onClick={start} disabled={isScanning}>Start Scan</button>
      <button onClick={stop} disabled={!isScanning}>Stop</button>
 
      {isScanning && <p>Progress: {Math.round(progress * 100)}%</p>}
      {error && <p>Error: {error.message}</p>}
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}

Return values:

Utility hooks and helpers

When you're driving the camera and feedback UI yourself, three additional helpers from @circadify/web-sdk/react make custom flows easier:

• useCamera({ videoRef, timeoutMs }) -- encapsulated getUserMedia lifecycle with permission and timeout handling. Returns { status, error, start, stop } with errors mapped to typed CircadifyError codes.
• summarizeQuality({ state, faceDetected }) and detailFor(channel, state, faceDetected) -- derive the four-channel UI summary (Face / Light / Still / Forward) from the SDK's QualityState events. Use these to render your own quality pills or banners.
• formatVitals(result) and metricToClipboard(metric) -- produce metric-card-ready payloads from a VitalSignsResult, including pretty units and clipboard strings.

Cancellation with AbortController

You can pass an AbortController signal through the hook to allow cancellation:

function CancellableScan() {
  const controllerRef = useRef(null);
  const { start, stop, result } = useSession({ type: 'standard' });
 
  const handleStart = () => {
    controllerRef.current = new AbortController();
    start({ signal: controllerRef.current.signal });
  };
 
  const handleCancel = () => {
    controllerRef.current?.abort();
  };
 
  return (
    <div>
      <button onClick={handleStart}>Start</button>
      <button onClick={handleCancel}>Cancel</button>
    </div>
  );
}

Cleanup

The CircadifyProvider automatically calls sdk.destroy() when it unmounts, releasing camera streams, runtime resources, and event listeners. No manual cleanup is required in most cases.

If you need to manually destroy the SDK instance (for example, on logout), use the useCircadify hook:

const sdk = useCircadify();
sdk.destroy();

Next Steps

• Custom UI -- Build a fully custom interface
• SDK Methods -- Full method reference