@rific/scanner

Full-screen barcode scanner with animated overlays, pinch zoom, timeout ring, and scan tracking for React Native. Uses expo-camera for barcode scanning when injected.

Installation

npm install @rific/scanner react-native-gesture-handler react-native-worklets react-native-svg expo-camera

Optional (for richer UI):

npm install react-native-paper react-native-safe-area-context

None of expo-camera, react-native-paper, or react-native-safe-area-context are auto-detected. Configure them once, near your app root: every <Scanner> picks them up automatically, with nothing to repeat per screen:

import { configureScanner } from '@rific/scanner'
import * as ExpoCamera from 'expo-camera'
import * as RNPaper from 'react-native-paper'
import * as SafeAreaContext from 'react-native-safe-area-context'

configureScanner({ camera: ExpoCamera, paper: RNPaper, safeArea: SafeAreaContext })

Or mount ScannerProvider instead: it's a thin wrapper that just calls configureScanner() for you, for consistency with how the other @rific packages configure their own optional integrations:

import { ScannerProvider } from '@rific/scanner'

<ScannerProvider camera={ExpoCamera} paper={RNPaper} safeArea={SafeAreaContext}>
  {/* your app */}
</ScannerProvider>

Either way, this is one-time setup, not reactive state: call it once, before your first <Scanner> renders. Omit any of the three and you get a working fallback for just that one: no camera feed (a plain colored view instead), a simple fallback dot instead of Paper's icon buttons, and a fixed iOS-style top padding instead of real device insets.

camera/paper/safeArea are also available as per-instance props on <Scanner>, for the rare case where one particular screen needs something different from the configured default: a prop always overrides the configured value.

Usage

import { Scanner } from '@rific/scanner'

<Scanner
  accentColor='#6200ee'
  autoScan
  timeout={30}
  onScan={({ data, type }) => console.log(data, type)}
  onClose={() => navigation.goBack()}
  onSound={() => playBoop()}
  onVibrate={() => vibrate()}
  onTimeout={() => navigation.goBack()}
/>

With custom menu

renderMenu accepts a plain ReactNode rendered in the header. To let it toggle facing/torch, manage that state yourself and pass it back into Scanner via the facing/torch props:

import { useState } from 'react'
import { Scanner } from '@rific/scanner'

const [facing, setFacing] = useState<'front' | 'back'>('back')
const [torch, setTorch] = useState(false)

<Scanner
  onScan={handleScan}
  facing={facing}
  torch={torch}
  renderMenu={
    <MyMenu
      facing={facing}
      onFacingToggle={() => setFacing(facing === 'back' ? 'front' : 'back')}
      torch={torch}
      onTorchToggle={() => setTorch(!torch)}
    />
  }
/>

Props

Prop	Type	Default	Description
onScan	(result: ScanResult) => void	required	Called with { data, type } for each captured scan
accentColor	string	'#6200ee'	Color for overlays, timer ring, and buttons
autoScan	boolean	true	Auto-capture on detect; false = manual press
backgroundColor	string	'black'	Camera background color
barcodeTypes	string[]	all	Barcode types to detect (e.g. ['qr', 'ean13'])
camera	CameraModule	configureScanner()'s value	Overrides the configured camera for this one instance. See Installation.
captureIcon	IconSource		Icon for the capture button (string, ImageSourcePropType, or (props: { color, size }) => ReactNode)
children	ReactNode		Rendered over the camera
closeIcon	IconSource		Icon for the close button
disabledScanValues	string[]		Values to show as already-scanned (checked state)
disabledScanValueSet	ReadonlySet<string>		Set version of disabledScanValues (preferred for large lists)
facing	'front' | 'back'	'back'	Which camera to use
mode	'scan' | 'photo'	'scan'	'scan' detects barcodes; 'photo' turns the capture button into a shutter that calls onPhoto
onClose	() => void		Shows a close button; called on press
onDisabledScan	(value: string) => void		Called when a disabled value is pressed
onPermissionDenied	() => void		Called when camera permission is denied
onPhoto	(photo: PhotoResult) => void		Called with the captured photo when mode='photo'
onSound	() => void		Called on successful scan; play a sound here
onTimeout	() => void		Called when the timeout ring completes
onVibrate	() => void		Called on successful scan; trigger haptics here
paper	ScannerPaperModule	configureScanner()'s value	Overrides the configured paper for this one instance. See Installation.
pictureOptions	PictureOptions		Options passed to takePictureAsync when mode='photo'
renderCapture	(handlers: { onPress, onPressIn, onPressOut }) => ReactNode		Fully custom capture button; receives the press handlers to wire up
renderClose	(handlers: { onPress }) => ReactNode		Fully custom close button; receives the press handler to wire up
renderMenu	ReactNode		Custom content rendered in the header (e.g. a menu of torch/facing controls)
safeArea	SafeAreaModule	configureScanner()'s value	Overrides the configured safeArea for this one instance. See Installation.
scanIcon	IconSource		Icon shown on an unscanned overlay target
scanTimeout	number	0	Seconds before a scanned value reverts to unscanned; 0 = never
scannedIcon	IconSource		Icon shown on an already-scanned overlay target
style	ViewStyle		Style for the camera view
timeout	number	0	Seconds before onTimeout/onClose fires; 0 = no timeout
torch	boolean	false	Whether the torch/flashlight is enabled

ScanResult

type ScanResult = {
  data: string   // barcode value
  type: string   // barcode format (e.g. 'QR', 'EAN13')
}

PhotoResult

type PhotoResult = {
  uri: string
  width: number
  height: number
  base64?: string
}

PictureOptions

type PictureOptions = {
  quality?: number
  base64?: boolean
  exif?: boolean
  skipProcessing?: boolean
}

Peer dependencies

Required:

• react >= 18.0.0
• react-native >= 0.76.0
• react-native-gesture-handler >= 2.0.0
• react-native-worklets >= 0.7.0
• react-native-svg >= 13.0.0

Optional, none are auto-detected: configure them via configureScanner()/ScannerProvider (see Installation):

• expo-camera >= 15.0.0: barcode scanning; without it the camera renders as a blank view
• react-native-paper >= 5.0.0: richer scan-overlay icon buttons; without it falls back to a plain dot
• react-native-safe-area-context >= 5.0.0: proper notch/safe area handling; without it falls back to a fixed iOS top padding