QR scanning in Flutter is commonly used for login flows, payments, event check-ins, and device pairing. Flutter does not provide a built-in QR scanning API, so this functionality is implemented using plugins that integrate with native camera and barcode detection frameworks.
What is a QR scanner in Flutter?
A QR scanner in Flutter is a plugin-based solution that:
- Opens the device camera.
- Detects QR codes in real time.
- Returns the decoded value to the Flutter app.
On Android and iOS, QR scanners rely on native camera APIs and platform barcode detectors. On the web, scanning depends on browser camera access and has more limitations.
Most Flutter QR scanning packages focus on QR codes only. Support for other barcode formats depends on the chosen plugin.
Flutter QR code scanner example
A minimal example using mobile_scanner:
final controller = MobileScannerController();
@override
void initState() {
super.initState();
controller.start();
}
@override
void dispose() {
controller.dispose();
super.dispose();
}
MobileScanner(
controller: controller,
onDetect: (barcode, args) {
final String? code = barcode.rawValue;
if (code == null) return;
debugPrint('Scanned QR code: $code');
},
);
This widget opens the camera and continuously scans for QR codes until you stop or dispose of the controller.
Understanding the scan result
A common beginner confusion is expecting the scan result to be a simple string.
In reality, the scanner returns an object (often called Barcode). This object contains metadata about the scan. The actual decoded content is usually stored in fields like rawValue or displayValue.
If you try to print or display the entire object, you will often see something like Instance of 'Barcode'. To get the real content, always extract the string value explicitly.
Handling scan results safely
QR scanners may detect the same code multiple times while it stays in view.
In real applications, you usually:
- Ignore duplicate values.
- Stop the scanner after the first successful scan.
- Temporarily disable handling logic.
Without this, navigation or API calls may trigger multiple times.
QR scanning requires explicit camera permissions on each platform.
iOS (Info.plist)
On iOS, camera access must be declared in Info.plist using NSCameraUsageDescription.
The value of this key is shown directly to the user in the system permission dialog, so it must clearly explain why the camera is needed. Add a description like this "The app needs camera access to scan QR codes on tickets."
Using vague or placeholder text (for example "test" or "camera access") is a common reason for App Store rejection.
Android (AndroidManifest.xml)
On Android, camera permission must be declared in AndroidManifest.xml.
In addition:
- The permission must be requested at runtime.
- The user can deny or revoke it at any time.
Your app should always handle the case where camera permission is not granted and show a clear fallback or explanation.
QR scanner lifecycle and camera freezes
A very common issue is the camera freezing after navigating away and back to the scanner screen. This usually happens when the scanner controller is not properly managed.
The correct pattern is:
- Start the scanner in
initState. - Stop or dispose it in
dispose.
Camera resources must be released when the widget is removed from the tree. Failing to do this often results in a black or frozen camera preview when returning to the screen.
QR scanner on Flutter Web
QR scanning on Flutter Web works differently than on mobile.
Important limitations:
- Camera access depends on browser support.
- HTTPS is required.
- Performance varies significantly between browsers.
- Some mobile browsers have limited or unstable camera APIs.
For web apps, QR scanning should be treated as a best-effort feature rather than a guaranteed flow.
Common mistakes with QR scanning in Flutter
Typical beginner issues include:
- Missing or incorrect camera permission descriptions.
- Trying to display the entire scan result object instead of its string value.
- Triggering logic multiple times for one QR code.
- Not managing the scanner controller lifecycle.
- Assuming web scanning behaves the same as mobile.
