Building an interface for scanning documents with the Custom UI

DocumentCustomUIComponent

DocumentCustomUIComponent exposes an API that is used to configure a native camera view that allows document detection in real time. The component is designed to be used in a Capacitor app and provides a bridge between the native SDK and your web-based UI. The native camera view is rendered in relation to your web view, and the component provides methods to control the camera and receive document detection results.

Usage

The DocumentCustomUIComponent provides lifecycle methods that allow you to manage the camera view and handle frame updates. These methods include:

View lifecycle and frame updates

• attachScannerAtFrame: Attaches the scanner at explicit frame coordinates and registers result callbacks.
• attachScannerOnElement: Computes the frame from the provided HTMLElement, attaches the scanner, and registers result callbacks.
• updateScannerViewFrame: Repositions the scanner at explicit frame coordinates.
• updateScannerViewFrameFromElement: Recomputes the frame from the provided HTMLElement and repositions the scanner.
• detachScannerView: Detaches the scanner view and unregisters result callbacks.
• freezeCamera and unfreezeCamera: Pause and resume the camera preview without detaching the scanner view.

Attaching the scanner

When attaching, you must provide either a frame or an HTML element plus sendToBack. The scanner will be rendered in relation to the specified frame or element, and the camera preview will be displayed in that area.

sendToBack controls layering relative to the Capacitor WebView:

• false (default): The scanner is rendered in front of the WebView.
• true: The scanner is rendered behind the WebView. The WebView must be transparent over the scanner area for the camera preview to be visible.

Result handlers are registered as part of the attachment call, so events can be delivered immediately after attachment completes. You can also pass an initial configuration to apply scanner settings during attachment.

Updating the scanner frame

Call updateScannerViewFrame or updateScannerViewFrameFromElement at any time to keep the native view aligned with layout changes, such as orientation changes, resizing, or animated UI transitions.

Detaching the scanner

When scanning is no longer needed, call detachScannerView to remove the scanner view from the native hierarchy and unregister result callbacks. You can attach the scanner again later.

Handling document detection results

Document detection is handled through DocumentCustomUIResultCallbacks, which are registered when the scanner is attached. Native document scanner events are forwarded to the matching callbacks:

• onSnappedDocumentResult - Called when a document is snapped, either manually or automatically. It provides the original image, and if a document detection has occurred, the cropped document image.
• onFrameDetectionResult - Called when the live document frame detection status changes. It is used to provide guidance to the user on how to position the document in the camera view.
• onError - Called when an error is reported by the scanner or during result processing.

The component converts native payloads into SDK types (ImageRef, DocumentDetectionResult) before invoking callbacks.

Attach Scanner View with Result Handlers

loading...

See full example on GitHub

Example

View the example project for a complete implementation of the DocumentCustomUIComponent in a Capacitor app.

Want to scan longer than one minute?

Generate a free trial license to test the Scanbot SDK thoroughly.

Get free trial license

Scanbot SDK is part of the Apryse SDK product family

A mobile scan is just the start. With Apryse SDKs, you can expand mobile workflows into full cross‑platform document processing. Whether you need to edit PDFs, add secure digital signatures, or use a fast, customizable document viewer and editor, Apryse gives you the tools to build powerful features quickly.

Learn more

Was this helpful?