@moveris/cognito-check-react

React wrapper for the CognitoCheck verification widget.

Drop <CognitoCheck /> anywhere in your React app. The widget handles the full oval/camera/liveness capture flow and calls your onSuccess or onError callback when done.

Not using React? Use @moveris/cognito-check — the framework-agnostic Web Component that works with Angular, Vue, plain HTML, and any other stack.

How it works

1. User clicks the widget checkbox
2. Camera modal opens — oval guide + liveness capture runs
3. Frames are sent to Moveris for analysis
4. onSuccess or onError fires in your component
5. You decide what to do next (enable a submit button, update state, redirect, etc.)

Installation

npm install @moveris/cognito-check-react @moveris/cognito-check
# or
pnpm add @moveris/cognito-check-react @moveris/cognito-check

Quick start

import { useState } from 'react';
import { CognitoCheck } from '@moveris/cognito-check-react';

export function SignupForm() {
  const [verified, setVerified] = useState(false);

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" placeholder="Email" />

      <CognitoCheck
        apiKey="your-api-key"
        onSuccess={({ sessionId }) => {
          // Optionally verify sessionId on your server before enabling submit
          setVerified(true);
        }}
        onError={({ outcome, reason }) => {
          if (outcome === 'cancelled') return; // user closed the modal
          console.warn('Verification failed:', reason);
        }}
      />

      <button type="submit" disabled={!verified}>
        Create account
      </button>
    </form>
  );
}

Props

| Prop | Type | Required | Description | | ----------- | ---------------------------------------- | -------- | ------------------------------------------------------------------- | | apiKey | string | Yes | Your Moveris API key. Sent as X-API-Key on verification requests. | | onSuccess | (result: CognitoSuccessResult) => void | Yes | Called when the user passes verification. | | onError | (result: CognitoErrorResult) => void | Yes | Called when verification fails or the user cancels. | | style | React.CSSProperties | No | Inline styles for the widget container. |

CognitoSuccessResult

interface CognitoSuccessResult {
  outcome: 'pass';
  sessionId: string; // use this for server-side verification
}

CognitoErrorResult

interface CognitoErrorResult {
  outcome: 'fail' | 'cancelled';
  reason: string; // human-readable description
}

Placement and styling

The widget renders at a default width of 300px. Use style to control its position within your layout:

// Left-aligned in a flex column
<CognitoCheck
  apiKey="your-api-key"
  onSuccess={...}
  onError={...}
  style={{ alignSelf: 'flex-start' }}
/>

// Centered
<CognitoCheck
  apiKey="your-api-key"
  onSuccess={...}
  onError={...}
  style={{ margin: '0 auto' }}
/>

The camera modal always renders as a full-viewport overlay (portal to document.body) — it is unaffected by your layout's overflow, transform, or z-index.

Handling outcomes

onError covers two distinct cases — distinguish with outcome:

<CognitoCheck
  apiKey="your-api-key"
  onSuccess={({ sessionId }) => {
    setVerified(true);
  }}
  onError={({ outcome, reason }) => {
    if (outcome === 'cancelled') {
      // User closed the modal — no action needed
      return;
    }
    // outcome === 'fail' — liveness check did not pass
    setError('Verification failed. Please try again.');
  }}
/>

Full example

import { useState } from 'react';
import { CognitoCheck } from '@moveris/cognito-check-react';

export function SignupForm() {
  const [verified, setVerified] = useState(false);
  const [error, setError] = useState<string | null>(null);

  return (
    <form>
      <input type="email" placeholder="Email" required />
      <input type="password" placeholder="Password" required />

      <CognitoCheck
        apiKey={import.meta.env.VITE_MOVERIS_API_KEY}
        onSuccess={() => {
          setVerified(true);
        }}
        onError={({ outcome, reason }) => {
          if (outcome !== 'cancelled') setError(reason);
        }}
        style={{ margin: '16px 0' }}
      />

      {error && <p style={{ color: 'red', fontSize: 13 }}>{error}</p>}

      <button type="submit" disabled={!verified}>
        Create account
      </button>
    </form>
  );
}