mobile_scanner

A fast and lightweight Flutter plugin for scanning barcodes and QR codes using the device’s camera. It supports multiple barcode formats, real-time detection, and customization options for an optimized scanning experience on multiple platforms.

Features

• Fast barcode and QR code scanning
• Supports multiple barcode formats
• Real-time detection
• Customizable camera and scanner behavior

See the examples for runnable examples of various usages, such as the basic usage, applying a scan window, or retrieving images from the barcodes.

Platform Support

Android	iOS	macOS	Web	Linux	Windows
✔	✔	✔	✔	:x:	:x:

Features Supported

See the example app for detailed implementation information.

Features	Android	iOS	macOS	Web
analyzeImage	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:x:
returnImage	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:x:
scanWindow	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:x:
autoZoom	:heavy_check_mark:	:x:	:x:	:x:
lensType	:heavy_check_mark:	:heavy_check_mark:	:x:	:x:
getSupportedLenses(facing:)	:heavy_check_mark:	:heavy_check_mark:	:x:	:x:
getBestCloseRangeScanningLens	:heavy_check_mark: (always normal)	:heavy_check_mark: (requires iOS 15, falls back to normal)	:x: (always normal)	:x: (always normal)

Querying supported lens types with facing filter

Use getSupportedLenses() to query which lens types the device has. Pass an optional facing parameter to restrict results to cameras on one side:

// All cameras (back + front)
final Set<CameraLensType> allLenses = await controller.getSupportedLenses();

// Back cameras only
final Set<CameraLensType> backLenses = await controller.getSupportedLenses(
  facing: CameraFacing.back,
);

if (backLenses.contains(CameraLensType.zoom)) {
  // Device has a telephoto back camera
}

Without a facing filter, results may include lenses from both the front and back cameras, which can cause incorrect lens-type detection when switching cameras.

The facing filter is supported on Android and iOS. On macOS and the web, the filter is ignored and all lenses are returned.

Automatic best-lens selection for close-range scanning

Use getBestCloseRangeScanningLens() to determine which lens can focus closest to the phone, and is therefore best suited for scanning barcodes held at close range. It returns null if the device has no camera for the given facing direction. Combine it with getSupportedLenses before switching, since the returned lens type is not guaranteed to be available:

final bestLens = await controller.getBestCloseRangeScanningLens(facing: CameraFacing.back);
final supported = await controller.getSupportedLenses(facing: CameraFacing.back);

if (bestLens != null && supported.contains(bestLens)) {
  await controller.switchCamera(
    SelectCamera(facingDirection: CameraFacing.back, lensType: bestLens),
  );
}

This returns:

• iOS 15+: The camera with the shortest AVCaptureDevice.minimumFocusDistance — typically the ultra-wide lens on newer iPhones (macro autofocus at ~2cm), or the standard 1x camera on older models
• iOS < 15 / macOS: CameraLensType.normal, since minimumFocusDistance is not available
• Android: CameraLensType.normal when the device has a camera. LENS_INFO_MINIMUM_FOCUS_DISTANCE is only meaningful on physical sub-cameras, which — like the rest of getSupportedLenses — are not independently selectable through CameraX, so the main camera (which has the most capable autofocus on virtually all Android devices) is returned unconditionally
• Web: CameraLensType.normal when the device has a camera. The MediaDevices API has no concept of lens type, and its focusDistance capability, where available at all, is limited to Chrome on Android
• All platforms: null if there is no camera for the requested facing direction

Installation

Add the dependency in your pubspec.yaml file:

dependencies:
  mobile_scanner: ^<latest_version>

Then run:

flutter pub get

Configuration

Android

This package uses by default the bundled version of MLKit Barcode-scanning for Android. This version is immediately available to the device. But it will increase the size of the app by approximately 3 to 10 MB.

The alternative is to use the unbundled version of MLKit Barcode-scanning for Android. This version is downloaded on first use via Google Play Services. It increases the app size by around 600KB.

You can read more about the difference between the two versions here.

To use the unbundled version of the MLKit Barcode-scanning, add the following line to your /android/gradle.properties file:

dev.steenbakker.mobile_scanner.useUnbundled=true

iOS

Since the scanner needs to use the camera, add the following keys to your Info.plist file. (located in /ios/Runner/Info.plist)

NSCameraUsageDescription - describe why your app needs access to the camera. This is called Privacy - Camera Usage Description in the visual editor.

If you want to use the local gallery feature from image_picker, you also need to add the following key.

NSPhotoLibraryUsageDescription - describe why your app needs permission for the photo library. This is called Privacy - Photo Library Usage Description in the visual editor.

Example,

<key>NSCameraUsageDescription</key>
<string>This app needs camera access to scan QR codes</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs photos access to get QR code from photo library</string>

macOS

Ensure that you granted camera permission in XCode -> Signing & Capabilities:

Web

As of version 5.0.0 adding the barcode scanning library script to the index.html is no longer required, as the script is automatically loaded on first use.

Detection backends

The web implementation supports three barcode detection backends. The active backend is selected via MobileScannerPlatform.instance.setWebBarcodeReader(reader) before starting the scanner.

Auto (default)

Uses the native BarcodeDetector API when the browser supports it, and falls back to zxing-wasm otherwise. This is the recommended setting for most apps.

Native BarcodeDetector

Uses the W3C Shape Detection API, which is built into the browser. No external library is loaded. This is the fastest option because detection runs natively without any JavaScript or WebAssembly overhead.

Available in Chrome 83+, Edge 83+, and Safari 17+. Not supported in Firefox.

zxing-wasm

Uses zxing-wasm, a WebAssembly port of the ZXing C++ library. The WASM binary (~2 MB) is loaded from the jsDelivr CDN on first use. Offers good performance and works in all modern browsers, including Firefox.

ZXing-js (legacy)

Uses the ZXing JavaScript library, a pure-JavaScript port of ZXing. Loaded from the unpkg CDN. This backend is slower than the WASM alternative and is provided for backward compatibility and comparison purposes only.

Backend comparison

Feature	Native BarcodeDetector	zxing-wasm	ZXing-js (legacy)
Performance	Fastest (native)	Fast (WASM)	Slow (pure JS)
Firefox	:x:	:heavy_check_mark:	:heavy_check_mark:
Chrome / Edge	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
Safari	17+	:heavy_check_mark:	:heavy_check_mark:
External dependency	None	~2 MB WASM (CDN)	~600 KB JS (CDN)
Supported formats	Browser-dependent	Most 1D and 2D formats	Most 1D and 2D formats

Barcode format support per backend

BarcodeFormat	Native BarcodeDetector ¹	zxing-wasm	ZXing-js (legacy)
aztec	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark: ³
codabar	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
code39	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
code93	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
code128	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
dataMatrix	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
ean8	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
ean13	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
itf ²	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
pdf417	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark: ³
qrCode	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
upcA	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
upcE	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
maxiCode	:x:	:heavy_check_mark:	:heavy_check_mark:
microQrCode	:x:	:heavy_check_mark:	:heavy_check_mark:
dataBar ⁴	:x:	:heavy_check_mark:	:heavy_check_mark:
dataBarExpanded ⁴	:x:	:heavy_check_mark:

¹ The BarcodeDetector API defines all formats listed, but the formats that are actually detected vary per browser and operating system. Use BarcodeDetector.getSupportedFormats() to query the current browser. In WebBarcodeReader.auto mode, mobile_scanner falls back to zxing-wasm when the brow