Skip to content

Your own interface ​

Without a template, BarcodeScanner shows the camera with a scan window, and overlayBuilder draws the rest. ScannerLayout gives the scan window and each barcode's corners already in widget coordinates.

dart
class ScanPage extends StatefulWidget {
  const ScanPage({super.key});

  @override
  State<ScanPage> createState() => _ScanPageState();
}

class _ScanPageState extends State<ScanPage> {
  // Created once, not in build; disposed with the page.
  final controller = ScannerController(
    formats: {BarcodeFormat.qrCode, BarcodeFormat.ean13},
    scanWindow: const ScanWindow.centered(width: 0.8, aspectRatio: 1.6),
  );

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => BarcodeScanner(
    controller: controller,
    onDetect: (capture) async {
      await controller.pause();
      // Show the result, then: await controller.resume();
    },
    overlayBuilder: (context, layout) => Stack(
      children: [
        ScannerOverlay(layout),
        Align(
          alignment: Alignment.bottomCenter,
          child: TorchButton(controller),
        ),
      ],
    ),
  );
}

The layout ​

ScannerLayoutWhat it is
sizeThe size of the scanner widget
scanWindowThe scan window, a Rect in the widget
barcodesThe codes in view, each a VisibleBarcode with its corners and bounds in the widget, and an id that stays while it stays in view
previewRectWhere the whole camera preview lies; with BoxFit.cover it reaches past the widget
stateThe camera state: status, torch, zoom
controllerThe controller, for buttons
dart
Widget labels(BuildContext context, ScannerLayout layout) => Stack(
  children: [
    for (final VisibleBarcode code in layout.barcodes)
      Positioned.fromRect(
        rect: code.bounds,
        child: DecoratedBox(
          decoration: BoxDecoration(
            border: Border.all(color: Colors.greenAccent, width: 3),
            borderRadius: BorderRadius.circular(8),
          ),
        ),
      ),
  ],
);

The pieces of the templates ​

The widgets the templates are built from are public, and take the scanner's theme:

WidgetWhat it is
ScannerOverlayThe scan window, the dimmed camera around it and the outlines of the codes
ScanWindowOverlay, BarcodeOutlinesThe window alone, the outlines alone
TorchButton, SwitchCameraButton, ZoomButtons, PickImageButton, ScannerCloseButtonThe buttons
ScannerButton, ScannerHint, ScannerChip, ScannerGlassGlass buttons, hints, chips and panels of your own
ScannerSheet, BarcodeResultSheet, BarcodeListSheetSheets for a result or a list of codes
ScannerPlaceholder, ScannerErrorViewWhat shows while the camera starts, and when it cannot be used
BarcodeThumbnailThe picture of a code cut out of the frame

Over a template ​

foregroundBuilder adds a layer of your own over the template's, in every state of the camera, with the scanner's theme: a button beside the template's buttons. Leave the rest of the layer free of taps, so they reach the overlay and the camera.

dart
BarcodeScanner(
  template: const ScannerTemplate.minimal(),
  foregroundBuilder: (context, layout) => Positioned(
    left: 16,
    top: layout.scanWindow.bottom + 72,
    child: ScannerButton(
      icon: ScannerIcons.binary,
      label: 'Help',
      onPressed: () => print('help'),
    ),
  ),
)

Starting, errors and settings ​

BarcodeScannerWhat it does
placeholderBuilderShown while the camera is starting or stopped; ScannerPlaceholder by default
errorBuilderShown instead of the preview when the camera cannot be used, with the ScannerException; ScannerErrorView by default
onOpenSettingsOpens the app's settings, where the user allows the camera. Opening them needs a plugin such as app_settings.
fitHow the preview fills the widget; BoxFit.cover by default
tapToFocus, pinchToZoomFocus where the user taps, zoom with a pinch; both on
pauseWhenHiddenStop the camera while the scanner is not shown, such as on another tab; on

The camera errors are subclasses of ScannerException: CameraPermissionException when access is off, CameraNotFoundException, CameraInUseException, CameraUnsupportedException (the web over plain HTTP, for one) and CameraFailureException.