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.

Theming

The component automatically follows the host device/browser's prefers-color-scheme setting — no configuration needed. Dark mode (the default look) uses a navy background with white text/icons; light mode inverts to a white background with navy (#000D1A) text/icons.

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.

• 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. Caller-owned — the component never resets it, so set it back to false before starting a new document or the back-side animation persists into the next front-side capture.

• successTime: Number (milliseconds)
  How long the "photo taken" success overlay is shown after a capture, before the preview screen (or, if showPreviewScreen is false, the capture event) follows. Default: 1500.

• showPreviewScreen: Boolean
  Controls whether the post-capture preview screen (review/retake/end) is shown before dispatching capture. When false (the default), capture dispatches and the camera closes immediately after the success overlay, skipping the preview screen entirely. Opt in per integration — coordinate with your team before enabling, since it changes when capture/close fire. Default: false.

• 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.

• enableAutoCapture: Boolean
  Enables auto-capture as the launch mode. When true, the camera opens in auto-capture and (subject to enableAutoCaptureTimeout) the auto-capture timeout is armed. Default: true. As an HTML attribute use enable-auto-capture; removing the attribute restores the default.

• enableTapToCapture: Boolean
  Makes tap-to-capture available. When true and enableAutoCapture is false, the camera launches directly in tap-to-capture mode with the capture button shown immediately, and the auto-capture timeout is ignored. Default: true. As an HTML attribute use enable-tap-to-capture; removing the attribute restores the default.

• documentType: 'auto' | 'id' | 'passport' Selects capture guidance and AssureID DPI gating for ID cards or passports. Default: 'auto'. In auto, the SDK infers ID vs passport from the detected document aspect ratio; explicit id or passport values override inference.

  In auto mode, the visible reticle intentionally remains passport-shaped for the duration of the session. This keeps the capture guide visually stable while document-type inference settles and prevents the reticle from changing shape mid-capture. The capture pipeline still uses the inferred document type internally for guidance and AssureID DPI gating.

Capture Mode Behaviour

enableAutoCapture and enableTapToCapture together determine which mode the camera launches in and whether the user can switch modes:

enableAutoCapture	enableTapToCapture	Launch mode	Auto-capture toggle	Auto-capture timeout
true	true	Auto-capture	Shown after toggleAutoCaptureDelay	Armed (respects enableAutoCaptureTimeout)
true	false	Auto-capture	Never shown	Armed (respects enableAutoCaptureTimeout)
false	true	Tap-to-capture	Shown immediately (user can switch to auto-capture)	Ignored
false	false	Auto-capture	Shown after toggleAutoCaptureDelay	Armed

Setting both to false is a misconfiguration and is normalized to the default (both enabled) behaviour.

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
  • cleanLenseText
  • photoCapturedText

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

  • backButton
  • helpIcon
  • autoCaptureEnable
  • autoCaptureDisable
  • tapToCapture
  • closeHelpButton
  • helpSection

• generalInfoTexts: [String, String, String]
  Text shown in the general information section.
  First string: smart capture instructions (front of document).
  Second string: tap-to-capture instructions (front of document).
  Third string: instructions shown while showBackOfDocumentAnimation is true, regardless of capture mode.

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

  • title
  • body (front of document)
  • bodyBack (shown instead of body while showBackOfDocumentAnimation is true)
  • lightingTipText
  • framingTipText
  • steadyTipText
  • autoCaptureConfirmationText
  • strugglingText
  • closeHelpAltText

• previewScreenTexts: Object
  Overrides the post-capture preview screen (shown after a photo is taken, before the result is returned). Recognized keys:

  • title
  • body
  • photoAltText
  • examplesLinkText
  • continueButtonText
  • retakeButtonText
  • endCheckButtonText
  • goodLabel
  • goodCaption
  • badLabel
  • cornersCaption
  • coveredCaption
  • blurryCaption
  • glareCaption

• previewScreenAriaLabels: Object
  Supplies ARIA labels for the preview screen's buttons, independent of previewScreenTexts. Recognized keys:

  • examplesLink
  • continueButton
  • retakeButton
  • endCheckButton

• cancelConfirmationTexts: Object
  Overrides the "End identity check" confirmation modal, opened from the preview screen's End button. Recognized keys:

  • title
  • confirmButtonText
  • dismissButtonText

• cancelConfirmationAriaLabels: Object
  Supplies ARIA labels for the "End identity check" confirmation modal's buttons, independent of cancelConfirmationTexts. Recognized keys:

  • confirmButton
  • dismissButton

• qualityExamplesTexts: Object
  Overrides the good/bad quality examples screen, opened from the preview screen's examples link. Recognized keys:

  • title
  • goodLabel
  • goodCaption
  • badLabel
  • cornersCaption
  • coveredCaption
  • blurryCaption
  • glareCaption
  • closeAltText

Localization Example

All visible text and ARIA labels can be set at once to switch the UI to another language. Only provide the keys you want to override — any omitted keys fall back to the component defaults.

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

// Visible copy
documentCamera.texts = {
  autoCaptureText: 'Auto Capture',
  autoCaptureOnText: 'ON',
  autoCaptureOffText: 'OFF',
  cleanLenseText: 'Make sure your camera lens is clean and hold the device steady',
  photoCapturedText: 'Photo captured'
};

// Accessibility labels (ARIA)
documentCamera.ariaLabels = {
  backButton: 'Back',
  helpIcon: 'Open help',
  autoCaptureEnable: 'Enable auto capture',
  autoCaptureDisable: 'Disable auto capture',
  tapToCapture: 'Tap to Capture',
  closeHelpButton: 'Close help',
  helpSection: 'Help section.'
};

// Detection hints
documentCamera.hints = {
  moveCloserHint: { title: 'Document is too far', description: 'Fit your document fully within the frame.' },
  fixBlurHint: { title: 'Document is blurry', description: 'Clean your camera lens & hold your phone still' },
  fixGlareHint: { title: 'Glare detected', description: 'Move away from bright light' },
  outOfFrameHint: { title: 'Document not in frame', description: 'Position your whole ID inside of the frame' },
  capturingHint: { title: 'Document detected', description: 'Capturing...' }
};

// General instructions (index 0 = auto-capture, index 1 = tap-to-capture, index 2 = back of document)
documentCamera.generalInfoTexts = [
  'Position the PHOTO PAGE of your document within the frame below',
  'Position your identity document within the frame',
  'Position the PHOTO PAGE of your document within the frame below'
];

// Help panel
documentCamera.textsHelpSection = {
  title: 'How to take a photo of your identity document',
  body: 'Place your document PHOTO PAGE up on a flat surface and:',
  bodyBack: 'Place your document PHOTO PAGE up on a flat surface and:',
  lightingTipText: 'Use a well lit area but avoid any strong overhead lighting',
  framingTipText: 'Fill the entire frame with your document',
  steadyTipText: 'Hold your phone steady',
  autoCaptureConfirmationText: 'Once the picture is clear, we’ll automatically take a photo',
  strugglingText: 'Still struggling to take a photo, turn off Auto capture',
  closeHelpAltText: 'Close help'
};

// Preview screen (shown after a photo is taken)
documentCamera.previewScreenTexts = {
  title: 'Check the preview of your identity document',
  body: 'Check the photo of your document is clear, in focus and directly face on.',
  photoAltText: 'Preview of your captured identity document',
  examplesLinkText: 'Examples of good and bad quality photos',
  continueButtonText: 'Continue',
  retakeButtonText: 'Take another photo',
  endCheckButtonText: 'End identity check',
  goodLabel: 'Good',
  goodCaption: 'Photo is clear, in focus, and directly face on.',
  badLabel: 'Bad',
  cornersCaption: 'Photo must show all four corners.',
  coveredCaption: 'Document must not be covered.',
  blurryCaption: 'Photo must not be blurry.',
  glareCaption: 'Photo must not have glare.'
};

// Preview screen ARIA labels (independent of previewScreenTexts)
documentCamera.previewScreenAriaLabels = {
  examplesLink: 'Examples of good and bad quality photos',
  continueButton: 'Continue',
  retakeButton: 'Take another photo',
  endCheckButton: 'End identity check'
};

// "End identity check" confirmation modal (opened from the preview screen)
documentCamera.cancelConfirmationTexts = {
  title: 'Are you sure you want to end your identity check?',
  confirmButtonText: 'Yes',
  dismissButtonText: 'No'
};

// Confirmation modal ARIA labels (independent of cancelConfirmationTexts)
documentCamera.cancelConfirmationAriaLabels = {
  confirmButton: 'Yes',
  dismissButton: 'No'
};

// Good/bad quality examples screen (opened from the preview screen)
documentCamera.qualityExamplesTexts = {
  title: 'Examples of good and bad quality photos',
  goodLabel: 'Good',
  goodCaption: 'Photo is clear, in focus, and directly face on.',
  badLabel: 'Bad',
  cornersCaption: 'Photo must show all four corners.',
  coveredCaption: 'Document must not be covered.',
  blurryCaption: 'Photo must not be blurry.',
  glareCaption: 'Photo must not have glare.',
  closeAltText: 'Close'
};

Lifecycle Overview

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

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). The "photo taken" success overlay shows for successTime ms.
4. preview (optional, opt-in): The camera hardware releases and the user reviews the photo, with the option to Continue, Retake, or End the identity check. Only happens when showPreviewScreen is set to true — see the Core Properties section.
5. 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 exits the document camera without the flow completing normally — either by clicking the back arrow before capturing, or by choosing "End identity check" from the preview screen after a successful capture (see showPreviewScreen). detail does not distinguish between these two cases. 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>

Launching in Tap-to-Capture Mode

<live-document-camera
  id="live-document-camera"
  enable-auto-capture="false"
  enable-tap-to-capture="true">
</live-document-camera>

Or in JavaScript:

const camera = document.getElementById('live-document-camera');
camera.enableAutoCapture = false;
camera.enableTapToCapture = true;

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
}