@ngmthaq20/react-face-id-capture

React component for face registration with real-time face detection and multi-angle capture. Guides users through capturing 6 face poses (center, top, top-left, top-right, left, right) using AI-powered face detection.

Installation

yarn add @ngmthaq20/react-face-id-capture

Peer Dependencies

yarn add react react-dom i18next react-i18next

i18next and react-i18next are optional — the component will auto-initialize i18n if your app doesn't already use it.

Quick Start

import { FaceRegister } from "@ngmthaq20/react-face-id-capture";

function App() {
  return (
    <FaceRegister
      onComplete={(captures) => {
        // captures: array of 6 face images
        captures.forEach((c) => {
          console.log(c.step); // "center" | "top" | "topLeft" | "topRight" | "left" | "right"
          console.log(c.labelKey); // translation key for the step label
          console.log(c.data); // base64 JPEG data URL
        });
      }}
      onExit={() => {
        // Called when user taps back on intro or discard on result screen
        console.log("User exited");
      }}
    />
  );
}

Props

| Prop | Type | Description | | -------------- | ------------------------------- | ------------------------------------------------------------------------------- | | onComplete | (captures: Capture[]) => void | Called when all 6 face images are captured and user taps "Save & Continue" | | onExit | () => void | Called when user taps back on intro screen or "Discard & Exit" on result screen | | locale | string | Override the active language ("en", "ja", or custom) | | translations | FaceRegisterTranslations | Override or extend translation strings |

Capture Object

interface Capture {
  step: "center" | "top" | "topLeft" | "topRight" | "left" | "right";
  labelKey: string; // i18n key for the step label (e.g. "faceRegister.labelCenter")
  data: string; // base64 JPEG data URL
}

Internationalization

Built-in languages: English (en) and Japanese (ja).

Change language

<FaceRegister locale="ja" onComplete={handleComplete} />

Override specific strings

<FaceRegister
  translations={{
    introTitle: "Verify Your Identity",
    getStarted: "Begin Scan",
    save: "Confirm & Continue",
  }}
  onComplete={handleComplete}
/>

Add a custom language

<FaceRegister
  locale="ko"
  translations={{
    introTitle: "얼굴 등록",
    introSub: "본인 확인을 위해 얼굴 프로필을 설정합니다",
    getStarted: "시작하기",
    // ... all keys
  }}
  onComplete={handleComplete}
/>

All Translation Keys

| Key | Default (EN) | | ------------------- | ------------------------------------------- | | introTitle | Face Registration | | introSub | Set up your face profile for identification | | introStep1 | Position your face within the oval frame | | introStep2 | Follow the crosshair by moving your head | | introStep3 | Hold still during the countdown to capture | | getStarted | Get Started | | back | Back | | hudTitle | Face Registration | | hudProgress | {{current}} / {{total}} | | stepCenter | Look straight ahead | | stepTop | Tilt your face up | | stepTopLeft | Tilt your face up and left | | stepTopRight | Tilt your face up and right | | stepLeft | Turn your face left | | stepRight | Turn your face right | | outsideOval | Move your face into the oval | | maskWarning | We need to see your full face | | maskWarningDetail | Make sure nothing is covering your face | | labelCenter | Center | | labelTop | Top | | labelTopLeft | Top Left | | labelTopRight | Top Right | | labelLeft | Left | | labelRight | Right | | resultTitle | Registration Complete | | resultSub | {{count}} face images captured successfully | | registerAgain | Register Again | | save | Save & Continue | | discard | Discard & Exit | | loadingModels | Loading face detection models... |

Exported Types

import type {
  Capture,
  FaceRegisterProps,
  FaceRegisterTranslations,
  StepName,
} from "@ngmthaq20/react-face-id-capture";

How It Works

1. Intro Screen — Instructions with a "Get Started" button
2. Capture Screen — Camera feed with an oval overlay and crosshair guide. The component detects the user's face in real-time and validates head position (yaw, pitch, roll). When the pose matches, a countdown triggers and the frame is captured automatically.
3. Result Screen — Displays all 6 captured images in a grid with "Save & Continue", "Register Again", and "Discard & Exit" options.

Requirements

• HTTPS required for camera access (except localhost)
• Face detection models are loaded from CDN (@vladmandic/face-api)
• Works on desktop and mobile browsers

License

MIT