Document Camera Frame #

DocumentCameraFrame is a powerful Flutter package for document scanning via a live camera feed. It offers a fully customizable UI and professional-grade capture workflows for IDs, passports, and general documents.

Key Features:

Smart Capture: Choose between single-sided or dual-sided modes (Front/Back) with built-in side indicators and smooth transitions.
Edge Detection: Real-time automatic document detection and precise cropping.
On-Device OCR: Set enableExtractText: true for instant text extraction (frontOcrText / backOcrText). No API keys, no internet, and 100% privacy (supports Latin scripts).
Fully Customizable: Modern modular styling for frames, buttons, animations, and instructions.
Offline-First: All processing happens on-device for maximum speed and security.

Demo #

Here's a quick preview of DocumentCameraFrame in action:

Auto document edge detection in real-time	Driver license dual-side capture (320×200) with auto-capture and side indicators
Passport scanning (300×450) with manual capture button, no side indicators, and custom instructions	ID card dual-side capture (320×200) with auto-capture, hidden side indicators, and smooth transitions

Features #

📸 Live Camera Preview with adjustable document frame
✂️ Custom Frame Dimensions for precise cropping
🔎 Automatic Document Detection
🔄 Dual-Side Capture Support (e.g., ID front/back)
📝 Optional on-device OCR — set enableExtractText: true to get extracted text in the save callback (no API key, no internet). OCR is Latin-only (no Arabic).
🎛️ Fully Customizable UI — titles, padding, button styles
🪝 Easy Event Callbacks — onDocumentSaved, onFrontCaptured, onBackCaptured, onRetake

Quick Start #

Installation #

Add the package to your Flutter project using:

flutter pub add document_camera_frame

Minimal Example #

import 'package:document_camera_frame/document_camera_frame.dart';
import 'package:flutter/material.dart';

class QuickExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return DocumentCameraFrame(
      frameWidth: 320,
      frameHeight: 200,
      requireBothSides: false,
      enableAutoCapture: true, // Enable automatic capture
      onDocumentSaved: (documentData) {
        print('Document saved: ${documentData.frontImagePath}');
        Navigator.pop(context);
      },
    );
  }
}

OCR (Text extraction) #

Note: OCR is Latin-only (no Arabic). The on-device ML Kit model supports English and other Latin-script languages only.

Set enableExtractText: true to run on-device text recognition after capture. The onDocumentSaved callback then receives DocumentCaptureData with:

frontImagePath / backImagePath — image file paths (unchanged)
frontOcrText / backOcrText — extracted text (when enableExtractText is true)

No API key or internet is required. OCR uses Google ML Kit and supports Latin script (English and other Latin-based languages). Arabic is not supported by the on-device model.

DocumentCameraFrame(
  frameWidth: 320,
  frameHeight: 200,
  enableExtractText: true,
  onDocumentSaved: (data) {
    print('Front text: ${data.frontOcrText}');
    print('Back text: ${data.backOcrText}');
  },
)

For custom OCR (e.g. from file paths elsewhere), use the exported OcrService class and its extractText(String imagePath) method.

Setup Requirements #

iOS Setup #

Set the minimum iOS deployment target to 15.5 or higher in your ios/Podfile:

platform :ios, '15.5'  # or newer version

Add the following keys to your ios/Runner/Info.plist file to request camera and microphone permissions:


<plist version="1.0">
    <dict>
        <!-- Add the following keys inside the <dict> section -->
        <key>NSCameraUsageDescription</key>
        <string>We need camera access to capture documents.</string>
        <key>NSMicrophoneUsageDescription</key>
        <string>We need microphone access for audio-related features.</string>
    </dict>
</plist>

Android Setup #

Update the minSdkVersion to 21 or higher in android/app/build.gradle:

android {
    defaultConfig {
        minSdk 21
    }
}

Add these permissions to your AndroidManifest.xml file:


<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-feature android:name="android.hardware.camera" />
    <uses-feature android:name="android.hardware.camera.autofocus" />

    <application android:label="MyApp" android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">
        <!-- Activities and other components -->
    </application>

</manifest>

Handling Camera Access Permissions #

Permission errors may occur when initializing the camera. You must handle them appropriately. Below are the possible error codes:

Error Code	Description
`CameraAccessDenied`	User denied camera access permission.
`CameraAccessDeniedWithoutPrompt`	iOS only. User previously denied access and needs to enable it manually via Settings.
`CameraAccessRestricted`	iOS only. Camera access is restricted (e.g., parental controls).
`AudioAccessDenied`	User denied microphone access permission.
`AudioAccessDeniedWithoutPrompt`	iOS only. User previously denied microphone access and needs to enable it manually via Settings.
`AudioAccessRestricted`	iOS only. Microphone access is restricted (e.g., parental controls).

Common Use Cases #

Driver's License (Both Sides) #

DocumentCameraFrame(
  frameWidth: 320,
  frameHeight: 200,
  frontSideTitle: Text('Scan Front of License', 
    style: TextStyle(color: Colors.white)),
  backSideTitle: Text('Scan Back of License',
    style: TextStyle(color: Colors.white)),
  requireBothSides: true,
  enableAutoCapture: true, // Automatically capture when document is aligned
  onFrontCaptured: (imagePath) => print('Front: $imagePath'),
  onBackCaptured: (imagePath) => print('Back: $imagePath'),
  onDocumentSaved: (data) => handleDocument(data),
)

Passport (Single Side) #

DocumentCameraFrame(
  frameWidth: 300,
  frameHeight: 450,
  title: Text('Scan Passport', style: TextStyle(color: Colors.white)),
  requireBothSides: false,
  showSideIndicator: false,
  enableAutoCapture: false, // Manual capture only
  frontSideInstruction: "Position passport within the frame",
  onDocumentSaved: (data) => handlePassport(data),
)

ID Card with Custom Styling #

DocumentCameraFrame(
  frameWidth: 320,
  frameHeight: 200,
  requireBothSides: true,
  enableAutoCapture: true,
  captureButtonText: "Take Photo",
  saveButtonText: "Done",
  retakeButtonText: "Try Again",
  progressIndicatorColor: Colors.blue,
  outerFrameBorderRadius: 16.0,
  onDocumentSaved: (data) => processIdCard(data),
)

Widget Parameters #

Core Parameters #

Parameter	Type	Description	Required	Default Value
`frameWidth`	`double`	Width of the document capture frame.	✅	—
`frameHeight`	`double`	Height of the document capture frame.	✅	—
`enableAutoCapture`	`bool`	Enables automatic capture when a document is properly aligned in the frame.	❌	`false`
`requireBothSides`	`bool`	Whether to require both sides (if false, can save with just front side).	❌	`true`
`showCloseButton`	`bool`	Flag to control the visibility of the CloseButton (optional).	❌	`false`
`cameraIndex`	`int?`	Index to specify which camera to use (e.g., 0 for back, 1 for front) (optional).	❌	`0` (back)
`bottomFrameContainerChild`	`Widget?`	Custom content for the bottom container (optional).	❌	`null`
`bottomHintText`	`String?`	Optional bottom hint text shown in the bottom container.	❌	`null`
`sideInfoOverlay`	`Widget?`	Optional widget shown on the right (e.g. a check icon).	❌	`null`
`showDetectionStatusText`	`bool`	Show the (dynamic) live detection status text (e.g. "Move closer").	❌	`true`

Styling Classes #

Parameter	Type	Description	Required	Default Value
`animationStyle`	`DocumentCameraAnimationStyle`	Animation styling configuration for the camera widget.	❌	`DocumentCameraAnimationStyle()`
`frameStyle`	`DocumentCameraFrameStyle`	Frame styling configuration for borders and appearance.	❌	`DocumentCameraFrameStyle()`
`buttonStyle`	`DocumentCameraButtonStyle`	Button styling configuration for all buttons.	❌	`DocumentCameraButtonStyle()`
`titleStyle`	`DocumentCameraTitleStyle`	Title styling configuration for screen titles.	❌	`DocumentCameraTitleStyle()`
`sideIndicatorStyle`	`DocumentCameraSideIndicatorStyle`	Side indicator styling configuration.	❌	`DocumentCameraSideIndicatorStyle()`
`progressStyle`	`DocumentCameraProgressStyle`	Progress indicator styling configuration.	❌	`DocumentCameraProgressStyle()`
`instructionStyle`	`DocumentCameraInstructionStyle`	Instruction text styling configuration.	❌	`DocumentCameraInstructionStyle()`

Callbacks #

Parameter	Type	Description	Required	Default Value
`onFrontCaptured`	`Function(String)?`	Callback triggered when front side is captured.	❌	`null`
`onBackCaptured`	`Function(String)?`	Callback triggered when back side is captured.	❌	`null`
`onDocumentSaved`	`Function(DocumentCaptureData)?`	Callback when document is saved (one-sided e.g. passport, or both sides). One of `onDocumentSaved` or `onBothSidesSaved` required.	✅*	—
`onBothSidesSaved`	`Function(DocumentCaptureData)?`	Deprecated. Use `onDocumentSaved` instead. Still supported for backward compatibility.	✅*	—
`enableExtractText`	`bool`	When true, runs on-device OCR and sets `documentData.frontOcrText` / `backOcrText` before the callback.	❌	`false`
`onRetake`	`VoidCallback?`	Callback triggered when the "Retake" button is pressed.	❌	`null`
`onCameraError`	`void Function(Object error)?`	Callback triggered when a camera-related error occurs (e.g., initialization, streaming, or capture failure).	❌	`null`

*At least one of onDocumentSaved or onBothSidesSaved must be provided. Prefer onDocumentSaved.

Styling Classes Details #

DocumentCameraAnimationStyle #

Property	Type	Description	Default Value
`capturingAnimationDuration`	`Duration?`	Duration for the capturing animation (optional).	`null`
`capturingAnimationColor`	`Color?`	Color for the capturing animation (optional).	`null`
`capturingAnimationCurve`	`Curve?`	Curve for the capturing animation (optional).	`null`
`frameFlipDuration`	`Duration`	Duration for the flip animation between sides.	`Duration(milliseconds: 1200)`
`frameFlipCurve`	`Curve`	Curve for the flip animation between sides.	`Curves.easeInOut`