📷 Modern Barcode Scanner

A high-performance barcode scanner React component with optimized detection, camera switching, torch control, and automatic phone detection.

---

✨ Features

• 🚀 High Performance: Web Worker-based scanning with optimized grayscale conversion.
• 📱 Mobile Optimized: Automatic phone detection with appropriate camera selection.
• 🔦 Torch Control: Built-in torch/flash support for low-light scanning.
• 🔄 Camera Switching: Easy switching between front and back cameras.
• 📷 Smart Camera Selection: Automatically selects the best rear camera (avoids ultra-wide/telephoto).
• 🎯 Session Management: Prevents stale results with session-based tracking.
• 🎨 Customizable UI: CSS-based styling with sensible defaults and CSS variables.
• 📦 TypeScript Support: Full type definitions included out of the box.
• 📳 Haptic Feedback: Standard Web Vibration API support for successful scans (Android/Desktop).
• 🔊 Sound Feedback: Optional audio cues on successful scans.

---

🏷️ Supported Barcode Formats

• 2D Codes: QR Code, PDF417
• Retail Codes: EAN-13, EAN-8, UPC-A, UPC-E
• Industrial/Standard Codes: Code 128, Code 39, Code 93, Codabar, ITF (Interleaved 2 of 5)
• Books: ISBN-10, ISBN-13
• DataBar (GS1)
• And more! (Powered by ZBar)

---

📦 Installation

Choose your preferred package manager:

# npm
npm install modern-barcode-scanner

# yarn
yarn add modern-barcode-scanner

# pnpm
pnpm add modern-barcode-scanner

---

🚀 Quick Start

Here's a minimal example to get the scanner up and running in your React application:

import { useRef, useEffect } from 'react';
import { BarcodeScanner, BarcodeScannerRef, ScanResult } from 'modern-barcode-scanner';

// Styles are auto-imported, but you can also import manually if needed:
// import 'modern-barcode-scanner/styles.css';

function App() {
  const scannerRef = useRef<BarcodeScannerRef>(null);

  const handleScan = (result: ScanResult) => {
    console.log('📦 Barcode type:', result.typeName);
    console.log('📄 Barcode data:', result.scanData);
    
    // Scanner automatically stops after detection.
    // Call scannerRef.current?.start() to scan again!
  };

  const handleError = (error: Error) => {
    console.error('❌ Scanner error:', error.message);
  };

  useEffect(() => {
    // Start scanning when component mounts
    scannerRef.current?.start();
  }, []);

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <BarcodeScanner
        ref={scannerRef}
        onScan={handleScan}
        onError={handleError}
        themeColor="#4db8a8" // Customize the primary UI color!
      />
    </div>
  );
}

WebAssembly (WASM) Configuration

Under the hood, this library uses @undecaf/zbar-wasm which relies on WebAssembly. Depending on your bundler, you may need to explicitly exclude it from dependency optimization or configure it to serve .wasm files correctly.

Vite Example (vite.config.ts):

export default defineConfig({
  // ... other config
  optimizeDeps: {
    exclude: ['@undecaf/zbar-wasm']
  }
});

---

📖 API Reference

<BarcodeScanner /> Component

Props

Prop	Type	Default	Description
onScan	(result: ScanResult) => void	Required	Callback fired when a barcode is detected.
onError	(error: Error) => void	undefined	Callback fired when an error occurs.
onStateChange	(state: ScannerState) => void	undefined	Callback fired when scanner state changes.
themeColor	string	'#4db8a8'	Primary theme color for UI elements and scan line.
scanInterval	number	100	Time between scan attempts (in ms).
enableVibration	boolean	true	Enable haptic feedback on scan (uses navigator.vibrate).
vibrationDuration	number	200	Vibration duration (in ms).
enableSound	boolean	false	Enable sound feedback on scan.
initialFacingMode	'user' | 'environment'	'environment'	Initial camera to use.
showScanLine	boolean	true	Show scanning animation line.
showCameraSwitch	boolean	true	Show camera switch button.
showTorchButton	boolean	true	Show torch button (if supported).
className	string	''	Custom CSS class for the container.
style	React.CSSProperties	undefined	Custom inline styles for the container.

Ref Methods

Exposed via useImperativeHandle for direct control:

interface BarcodeScannerRef {
  start: () => Promise<void>;        // Starts the camera and scanning
  stop: () => void;                  // Stops the camera and scanning
  switchCamera: () => Promise<void>; // Toggles between front and back camera
  toggleTorch: () => Promise<void>;  // Toggles the torch/flash (if supported)
  getState: () => ScannerState;      // Returns current state
}

TypeScript Types

interface ScanResult {
  typeName: string;  // e.g., 'QRCODE', 'EAN13', 'CODE128'
  scanData: string;  // The decoded barcode string
}

interface ScannerState {
  isScanning: boolean;
  facingMode: 'user' | 'environment';
  isTorchOn: boolean;
}

---

🛠️ Advanced Usage

Using the useScanner Hook

If you need complete control over the UI, you can use the internal hook directly:

import { useScanner } from 'modern-barcode-scanner';

function CustomScanner() {
  const {
    scannerState,
    videoRef,
    canvasRef,
    handleScan,
    handleStopScan,
    handleSwitchCamera,
    handleToggleTorch,
  } = useScanner({
    onScan: (result) => console.log('Scanned:', result),
    onError: (error) => console.error('Error:', error),
    enableVibration: true,
  });

  return (
    <div>
      <video ref={videoRef} autoPlay muted playsInline />
      <canvas ref={canvasRef} hidden />
      
      <div className="controls">
        <button onClick={handleScan}>▶️ Start</button>
        <button onClick={handleStopScan}>⏹️ Stop</button>
        <button onClick={handleSwitchCamera}>🔄 Switch</button>
        {scannerState.isTorchOn ? '🔦 On' : '🔦 Off'}
      </div>
    </div>
  );
}

Helper Utilities

The library exports several useful utilities:

import { 
  isPhone, 
  getBestRearCamera, 
  getMediaConstraints 
} from 'modern-barcode-scanner';

// 📱 Check if device is a phone/tablet
const isMobile = isPhone();

// 📷 Get the optimal rear camera device ID (avoids ultra-wide lenses)
const cameraId = await getBestRearCamera();

// ⚙️ Get optimized media constraints based on facing mode
const constraints = await getMediaConstraints('environment');

---

🎨 Styling

The component uses CSS prefix mbs- (Modern Barcode Scanner) and supports native CSS variables for easy theming.

CSS Variables

You can easily override the primary color globally or via the themeColor prop:

:root {
  --mbs-primary: #ff0055; /* Changes scan line and active icon colors */
}

Overriding Classes

/* Custom container styling */
.mbs-container {
  border-radius: 1rem;
  box-shadow: 0 4px 6px rgba(0,0,0,0.1);
}

/* Custom scan line */
.mbs-scan-line {
  height: 3px;
  box-shadow: 0 0 15px 3px var(--mbs-primary);
}

/* Custom control buttons */
.mbs-control-btn {
  background-color: rgba(255, 255, 255, 0.2);
  backdrop-filter: blur(4px);
}

---

🌐 Browser Support

Browser / OS	Version
🟢 Google Chrome	79+
🔵 Microsoft Edge	79+
🟠 Mozilla Firefox	79+
🧭 Safari (macOS)	14.1+
📱 Chrome for Android	Supported
🍎 Safari on iOS	14.5+

⚠️ Note: Camera access requires a secure context (HTTPS) in production environments!

---

⚡ Performance Optimizations

This library is built for speed and reliability:

1. Web Worker Processing: Barcode detection runs entirely off the main thread.
2. Grayscale Conversion: Uses bitwise operations for incredibly fast image matrix processing.
3. Frame Throttling: Configurable scanInterval perfectly balances detection speed with device battery/CPU usage.
4. Session Management: Strictly prevents processing out-of-date or stale video frames.
5. Smart Downscaling: Intelligently reduces image resolution for faster processing while maintaining read quality.
6. Canvas Optimizations: Utilizes willReadFrequently and desynchronized rendering hints where supported.

---

📝 License

MIT © Sumit Sahoo

Please refer to the LICENSE file for the full text.

---

🤝 Credits

• Powerful barcode detection engine powered by ZBar WASM.