Skip to main content

Document Camera

The Document Camera component provides a live camera interface for capturing identity documents. It includes real-time feedback, auto-capture, and customizable UI elements.

Properties​

Core Properties​

  • isOpen: Boolean
    Starts or stops the camera. When true, the camera feed and UI are rendered. Automatically set to false after capture or error.

  • showBackButton: Boolean
    Controls the visibility of the back button that allows users to exit the camera. Default: true.

  • showHelpIcon: Boolean
    Controls the visibility of the Help icon. Default: true.

  • showToggle: Boolean
    Controls the visibility of the Auto Capture toggle. Default: true.

  • toggleAutoCaptureDelay: Number (milliseconds)
    Delay before enabling the Auto Capture toggle after the initial animation completes. Default: 15000 (15s).

  • showBackOfDocumentAnimation: Boolean
    If true, shows the back-side animation first. Default: false.

  • successTime: Number (milliseconds)
    How long the success screen is shown after a capture. Default: 500.

  • autoCaptureTimeout: Number (milliseconds)
    Timeout duration for auto-capture. Must be greater than toggleAutoCaptureDelay. Default: 60000 (1 minute).

  • enableAutoCaptureTimeout: Boolean
    Enables or disables auto-capture timeout functionality. Default: true.

Detection Feedback​

  • hints: DocumentDetectionHint
    Customizes user guidance messages used by detection feedback. Any fields you omit fall back to sensible defaults.

  • cameraState: CameraState (read-only)
    Indicates the current detection state, e.g., MoveCloser, OutOfFrame, FixGlare, FixBlur, Countdown, Capturing, TapToCapture.

Text Customization​

The Document Camera component provides text and accessibility customization to support internationalization and accessibility.

Text precedence for visible copy:

  1. texts (provided keys)
  2. Component defaults

ARIA label precedence:

  1. ariaLabels (provided keys)
  2. Component defaults

  • texts: Object
    Overrides user-facing copy. Recognized keys:

    • autoCaptureText
    • autoCaptureOnText
    • autoCaptureOffText
    • alertText

  • ariaLabels: Object
    Supplies ARIA labels for interactive controls. Recognized keys:

    • backButton
    • helpIcon
    • autoCaptureEnable
    • autoCaptureDisable
    • tapToCapture
    • closeHelpIcon
    • closeHelpButton
    • helpAnimationGlare
    • helpAnimationBlur
    • helpAnimationTooFar

  • generalInfoTexts: [String, String]
    Text shown in the general information section.
    First string: smart capture instructions.
    Second string: tap-to-capture instructions.

  • textsHelpSection: Object
    Overrides the help panel text. Recognized keys:

    • title
    • body
    • tipsTitle
    • glareTipTitle, glareTipText
    • blurTipTitle, blurTipText
    • tooFarTipTitle, tooFarTipText
    • closeHelpAltText

Lifecycle Overview​

The Document Camera component provides a streamlined capture flow optimized for identity document scanning with real-time quality feedback.

Document Camera Lifecycle

Key Flow Stages:

  1. open: Camera initialized and WebRTC stream established
  2. detect loop: Continuous frame analysis checking for glare, blur, angle, DPI
  3. capture: When quality thresholds are met (auto) or user taps (manual)
  4. close: Camera closes and cleanup. The close event is always emitted after capture, userCanceled, failure, or timeout.

Events​

  • OpenEventName
    Triggered when the camera starts.

  • CloseEventName
    Triggered when the camera stops. This event is always emitted, regardless of how the camera session ends (successful capture, user cancellation, error, or timeout). After a successful capture, the capture event is dispatched first, followed by the close event.

  • UserCanceledEventName
    Triggered when the user clicks the back arrow and exits the document camera without capturing an image. The close event is dispatched after this event.

  • FailureEventName
    Triggered on error. detail.error is of type DocCameraError. The close event is dispatched after this event.

  • CaptureEventName
    Triggered on successful capture. detail.captureResponse contains capture data. The close event is dispatched after this event.

  • DetectEventName
    Triggered on each frame detection. detail includes detectResponse and cameraState.

Example Usage​

Basic Setup​

<live-document-camera
  id="live-document-camera"
  autoCaptureTimeout="120000"
  enableAutoCaptureTimeout="true">
</live-document-camera>

Handling Timeout Error​

const camera = document.getElementById('live-document-camera');

camera.addEventListener(LiveDocumentCamera.FailureEventName, (event) => {
  const error = event.detail.error;
  
  if (error.code === 'auto-capture-timeout') {
    // Handle timeout - e.g., show message to user
    console.log('Auto-capture timed out. Please use manual capture or offer to retry.');
  }
});

Type Definitions​

type DocumentDetectionHint = {
  moveCloserHint?: DocumentHint;
  fixBlurHint?: DocumentHint;
  fixGlareHint?: DocumentHint;
  outOfFrameHint?: DocumentHint;
  capturingHint?: DocumentHint;
};

type DocumentHint = {
  title: string;
  description: string;
};

type DocCameraError = {
  code: string;
  message: string;
};

type CaptureResponse = {
  isGood?: boolean;
  isSharp?: boolean;
  isGlareFree?: boolean;
  isAdequateDpi?: boolean;
  isPortraitOrientation?: boolean;
  failedChecks?: string[];
  imageData?: ImageData;
  imageWidth?: number;
  imageHeight?: number;
};

type DetectResponse = {
  isGood: boolean;
  isSharp?: boolean;
  isGlareFree?: boolean;
  isAdequateDpi?: boolean;
  failedChecks: string[];
  dimensions?: Dimension;
  corners?: MappedCorners;
};

type Dimension = {
  width: number;
  height: number;
};

type MappedCorners = {
  topLeft: Corner;
  topRight: Corner;
  bottomLeft: Corner;
  bottomRight: Corner;
};

type Corner = {
  x: number;
  y: number;
};

enum CameraState {
  MoveCloser,
  OutOfFrame,
  FixGlare,
  FixBlur,
  Countdown,
  Capturing,
  TapToCapture
}