Skip to content

Cognito Check React API & Props

Use this reference to configure CognitoCheck from @moveris/cognito-check-react.

In plain terms

The React wrapper has a small API: apiKey, onSuccess, onError, and optional style.

Import

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

Props

Prop Type Required Description
apiKey string Yes 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={handleSuccess}
  onError={handleError}
  style={{ alignSelf: 'flex-start' }}
/>

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

Modal rendering

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 them 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>
  );
}

Callback Guidance

  • onSuccess: Validate sessionId server-side before unlocking sensitive actions.
  • onError: Handle cancelled and fail differently for better UX.
  • style: Use for alignment and spacing, not for modal behavior.

Troubleshooting

Symptom Likely Cause Fix
Verification never starts Missing/invalid apiKey Confirm key value and environment injection
Form button never enables onSuccess not updating state Set verified state in onSuccess callback
User closes modal and sees error UI cancelled handled as fail Ignore or separately handle outcome === 'cancelled'
Build error on import.meta.env Missing Vite/bundler env support Use your build tool's env convention (e.g. process.env.NEXT_PUBLIC_...)

Next Steps