React Barcode Scanner API Reference – React Barcode Scanner

BarcodeScannerProvider

BarcodeScannerProvider creates an isolated stream and torch scope. It is optional; hooks outside a Provider continue to use the global compatibility scope.

Name	Type	Default	Description
`initialTorchOn`	`boolean`	`false`	Initial torch state, read once when the Provider store is created.
`children`	`ReactNode`	required	Scanner and state consumers that belong to this scope.


<BarcodeScannerProvider initialTorchOn={false}>
  <BarcodeScanner />
  <ScannerControls />
</BarcodeScannerProvider>

useStreamState() and useTorch() resolve the nearest Provider. Different Providers are isolated; without a Provider they resolve the module-level compatibility store.

The basic scope rules are explained in Getting Started.

BarcodeScanner

BarcodeScanner accepts the standard React video attributes in addition to these props:

Name	Type	Default	Description
`options`	`ScanOptions`	`DEFAULT_OPTIONS`	Scan interval and barcode formats.
`onCapture`	`(barcodes: DetectedBarcode[]) => void`	—	Called after one or more barcodes are detected.
`onCameraError`	`(error: Error) => void`	—	Called when camera initialization fails.
`onScanError`	`(error: Error) => void`	—	Called when the detector fails.
`trackConstraints`	`MediaTrackConstraints`	`DEFAULT_CONSTRAINTS`	Additional video track constraints.
`paused`	`boolean`	`false`	Pauses video playback and scanning without unmounting the component.

useCamera


function useCamera(
  ref: RefObject<HTMLVideoElement | null>,
  trackConstraints?: MediaTrackConstraints
): {
  isCameraReady: boolean
  error: Error | undefined
}

Creates the camera stream, assigns it to the video element and exposes initialization errors.

DEFAULT_CONSTRAINTS


{
  width: { min: 640, ideal: 1280 },
  height: { min: 480, ideal: 720 },
  facingMode: { ideal: 'environment' },
  advanced: [
    { width: 1920, height: 1280 },
    { aspectRatio: 1.333 }
  ]
}

useScanning


function useScanning(
  ref: RefObject<HTMLVideoElement | null>,
  options?: ScanOptions
): {
  detectedBarcodes: DetectedBarcode[] | undefined
  error: Error | undefined
  startScan: () => void
  stopScan: () => void
}

When the included react-barcode-scanner/polyfill is imported, the hook waits for it to finish loading before creating a detector. Other Barcode Detection API-compatible implementations are read from globalThis.BarcodeDetector. A detector is reused until formats changes.

DEFAULT_OPTIONS


{
  delay: 1000,
  formats: ['qr_code']
}

useTorch


function useTorch(defaultTorchOn?: boolean): {
  isTorchSupported: boolean
  error: Error | undefined
  isTorchOn: boolean
  setIsTorchOn: (torch: boolean) => void
}

Torch support depends on the active camera track and the browser/device capabilities.

useStreamState


function useStreamState(): [
  MediaStream | undefined,
  (newState: MediaStream | undefined) => void
]

Exposes the stream created by useCamera, including to components outside BarcodeScanner.

Without a BarcodeScannerProvider, useStreamState and useTorch use module-level shared state. Wrap each scanner and its consumers in a separate Provider when rendering multiple active scanners.

Types

ScanOptions


interface ScanOptions {
  delay?: number
  formats?: Array<BarcodeFormat | string>
}

DetectedBarcode


interface DetectedBarcode {
  boundingBox: DOMRectReadOnly
  cornerPoints: Point[]
  format: string
  rawValue: string
}