Document Camera Frame

DocumentCameraFrame is a Flutter package for scanning documents using a live camera feed. It provides a customizable frame UI, dual-side capture support (e.g., front/back of ID cards), automatic document detection, and easy integration for OCR or document processing workflows.

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)
• 🎛️ Fully Customizable UI — titles, padding, button styles
• 🪝 Easy Event Callbacks — onCaptured, onRetake, onSaved

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
      onBothSidesSaved: (documentData) {
        print('Document saved: ${documentData.frontImagePath}');
        Navigator.pop(context);
      },
    );
  }
}

Setup Requirements

iOS Setup

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

platform :ios, '15.5'  # or newer version

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

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

android {
    defaultConfig {
        minSdk 21
    }
}

2. 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:

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'),
  onBothSidesSaved: (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",
  onBothSidesSaved: (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,
  onBothSidesSaved: (data) => processIdCard(data),
)

Widget Parameters

Core Parameters

Styling Classes

Callbacks

Styling Classes Details

DocumentCameraAnimationStyle

DocumentCameraFrameStyle

DocumentCameraButtonStyle

DocumentCameraTitleStyle

DocumentCameraSideIndicatorStyle

DocumentCameraProgressStyle

DocumentCameraInstructionStyle

🔧 Troubleshooting

Common Issues

Camera not initializing:

• ✅ Check camera permissions in device settings
• ✅ Ensure minSdkVersion is at least 21 (Android)
• ✅ Verify camera permissions in Info.plist (iOS)

Build errors:

• 💡 Run flutter clean && flutter pub get
• 💡 Confirm all platform-specific setup is complete
• 💡 Ensure minimum iOS deployment target is 15.5 or higher in your ios/Podfile

Permission denied errors:

• ⚠️ Handle permission errors gracefully in your app UI
• ⚠️ Guide users to enable permissions in device settings

⚙️ Performance Tips

• 📱 The package automatically manages camera resources
• 🗂️ Images are saved to the temporary directory by default
• 🚫 Consider implementing proper error handling for production apps

📌 Full Example

For a comprehensive example with multiple document types, see
example/main.dart.

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.

🙌 Support

• 🐛 Bug reports: Please open issues on GitHub Issues
• 💡 Feature requests: Share your ideas on GitHub Discussions
• ⭐ Enjoying this package? Please give it a star on GitHub or like it on pub.dev

License

This project is licensed under the MIT License. See the LICENSE file for details.