@yudiel/react-qr-scanner

A modern React library for scanning QR codes and barcodes using your device camera or webcam. Built on top of the Barcode Detection API with React hooks and components.

Features

• Multiple Barcode Formats - Supports QR codes, EAN, UPC, Code 128, and many more 1D/2D formats
• Camera Controls - Built-in torch (flashlight), zoom, and camera switching capabilities
• Flexible Scanning - Continuous scanning, single scan mode, or pause/resume functionality
• Custom Tracking - Draw custom overlays and tracking visualizations on detected barcodes
• Device Selection - Choose specific cameras with the useDevices hook
• Customizable UI - Custom styles, class names, and component overrides
• Audio Feedback - Optional beep sound on successful scans (with custom sound support)
• TypeScript Support - Fully typed for excellent developer experience
• Lightweight - Minimal dependencies with optimized bundle size
• Cross-browser Compatible - Works across modern browsers with webrtc-adapter

Table of Contents

• Demo
• Installation
• Quick Start
• Usage Examples
  • Basic Scanner
  • Device Selection
  • Camera Constraints
  • Custom Tracking Overlay
  • Pausing and Resuming
  • UI Components
• API Reference
  • Scanner Props
  • useDevices Hook
• Supported Formats
• Type Definitions
• Browser Support
• Limitations
• Contributing
• License

Demo

Check out the live demo to see the scanner in action.

Installation

npm install @yudiel/react-qr-scanner

yarn add @yudiel/react-qr-scanner

pnpm add @yudiel/react-qr-scanner

Quick Start

import { Scanner } from '@yudiel/react-qr-scanner';

function App() {
  return (
    <Scanner
      onScan={(result) => console.log(result)}
      onError={(error) => console.log(error?.message)}
    />
  );
}

Usage Examples

Basic Scanner

import { Scanner } from '@yudiel/react-qr-scanner';

function BasicExample() {
  const handleScan = (detectedCodes) => {
    console.log('Detected codes:', detectedCodes);
    // detectedCodes is an array of IDetectedBarcode objects
    detectedCodes.forEach(code => {
      console.log(`Format: ${code.format}, Value: ${code.rawValue}`);
    });
  };

  return (
    <Scanner
      onScan={handleScan}
      onError={(error) => console.error(error)}
    />
  );
}

Device Selection

Use the useDevices hook to list available cameras and select a specific device:

import { Scanner, useDevices } from '@yudiel/react-qr-scanner';
import { useState } from 'react';

function DeviceSelectionExample() {
  const devices = useDevices();
  const [selectedDevice, setSelectedDevice] = useState(null);

  return (
    <div>
      <select onChange={(e) => setSelectedDevice(e.target.value)}>
        <option value="">Select a camera</option>
        {devices.map((device) => (
          <option key={device.deviceId} value={device.deviceId}>
            {device.label || `Camera ${device.deviceId}`}
          </option>
        ))}
      </select>

      <Scanner
        onScan={(result) => console.log(result)}
        constraints={{
          deviceId: selectedDevice,
        }}
      />
    </div>
  );
}

Camera Constraints

Customize camera settings using MediaTrackConstraints:

import { Scanner } from '@yudiel/react-qr-scanner';

function ConstraintsExample() {
  return (
    <Scanner
      onScan={(result) => console.log(result)}
      constraints={{
        facingMode: 'environment', // Use rear camera
        aspectRatio: 1, // Square aspect ratio
        // Advanced constraints
        width: { ideal: 1920 },
        height: { ideal: 1080 },
      }}
    />
  );
}

Custom Tracking Overlay

Draw custom visualizations on detected barcodes:

import { Scanner } from '@yudiel/react-qr-scanner';

function TrackingExample() {
  const highlightCodeOnCanvas = (detectedCodes, ctx) => {
    detectedCodes.forEach((detectedCode) => {
      const { boundingBox, cornerPoints } = detectedCode;

      // Draw bounding box
      ctx.strokeStyle = '#00FF00';
      ctx.lineWidth = 4;
      ctx.strokeRect(
        boundingBox.x,
        boundingBox.y,
        boundingBox.width,
        boundingBox.height
      );

      // Draw corner points
      ctx.fillStyle = '#FF0000';
      cornerPoints.forEach((point) => {
        ctx.beginPath();
        ctx.arc(point.x, point.y, 5, 0, 2 * Math.PI);
        ctx.fill();
      });
    });
  };

  return (
    <Scanner
      onScan={(result) => console.log(result)}
      components={{
        tracker: highlightCodeOnCanvas,
      }}
    />
  );
}

Pausing and Resuming

Control when the scanner is active:

import { Scanner } from '@yudiel/react-qr-scanner';
import { useState } from 'react';

function PauseExample() {
  const [isPaused, setIsPaused] = useState(false);

  return (
    <div>
      <button onClick={() => setIsPaused(!isPaused)}>
        {isPaused ? 'Resume' : 'Pause'} Scanning
      </button>

      <Scanner
        onScan={(result) => console.log(result)}
        paused={isPaused}
      />
    </div>
  );
}

UI Components

Enable built-in UI controls for torch, zoom, and camera switching:

import { Scanner } from '@yudiel/react-qr-scanner';

function UIComponentsExample() {
  return (
    <Scanner
      onScan={(result) => console.log(result)}
      components={{
        audio: true, // Play beep sound on scan
        onOff: true, // Show camera on/off button
        torch: true, // Show torch/flashlight button (if supported)
        zoom: true, // Show zoom control (if supported)
        finder: true, // Show finder overlay
      }}
      // Custom sound (base64 encoded audio)
      sound="data:audio/mp3;base64,YOUR_BASE64_AUDIO_HERE"
    />
  );
}

API Reference

Scanner Props

Prop	Type	Required	Default	Description
onScan	(detectedCodes: IDetectedBarcode[]) => void	Yes	-	Callback function called when one or more barcodes are detected.
onError	(error: unknown) => void	No	-	Callback function called when an error occurs while accessing the camera.
constraints	MediaTrackConstraints	No	{}	Media track constraints to apply to the video stream (e.g., facingMode, deviceId).
formats	BarcodeFormat[]	No	All	Array of barcode formats to detect. If not specified, all supported formats are detected.
paused	boolean	No	false	If true, the scanner pauses and displays the last frame.
children	ReactNode	No	-	Custom children to render inside the scanner container.
components	IScannerComponents	No	{}	Configuration for built-in UI components and custom tracker function.
styles	IScannerStyles	No	{}	Custom CSS styles for scanner elements.
classNames	IScannerClassNames	No	{}	Custom CSS class names for scanner elements.
scanDelay	number	No	500	Delay in milliseconds between successful scans. Prevents duplicate detections.
allowMultiple	boolean	No	false	If true, allows the same barcode to trigger onScan multiple times.
sound	boolean | string	No	false	If true, plays default beep sound. Provide a base64 audio string for custom sound.

useDevices Hook

Returns an array of available video input devices (cameras).

const devices = useDevices();
// Returns: MediaDeviceInfo[]

Example:

import { useDevices } from '@yudiel/react-qr-scanner';

function CameraList() {
  const devices = useDevices();

  return (
    <ul>
      {devices.map((device) => (
        <li key={device.deviceId}>
          {device.label || `Camera ${device.deviceId}`}
        </li>
      ))}
    </ul>
  );
}

Supported Formats

The library supports detection of the following barcode formats:

1D Barcodes	2D Barcodes
Codabar	Aztec
Code 39	Data Matrix
Code 93	Matrix Codes
Code 128	Maxi Code
Databar	Micro QR Code
Databar Expanded	PDF 417
Dx Film Edge	QR Code
EAN 8	rMQR Code
EAN 13
ITF
Linear Codes
UPC A
UPC E

To detect specific formats only:

<Scanner
  onScan={(result) => console.log(result)}
  formats={['qr_code', 'ean_13', 'code_128']}
/>

Type Definitions

BarcodeFormat

type BarcodeFormat =
  | 'aztec'
  | 'code_128'
  | 'code_39'
  | 'code_93'
  | 'codabar'
  | 'databar'
  | 'databar_expanded'
  | 'data_matrix'
  | 'dx_film_edge'
  | 'ean_13'
  | 'ean_8'
  | 'itf'
  | 'maxi_code'
  | 'micro_qr_code'
  | 'pdf417'
  | 'qr_code'
  | 'rm_qr_code'
  | 'upc_a'
  | 'upc_e'
  | 'linear_codes'
  | 'matrix_codes'
  | 'unknown';

IDetectedBarcode

interface IDetectedBarcode {
  boundingBox: IBoundingBox;
  cornerPoints: IPoint[];
  format: string;
  rawValue: string;
}

IBoundingBox

interface IBoundingBox {
  x: number;
  y: number;
  width: number;
  height: number;
}

IPoint

interface IPoint {
  x: number;
  y: number;
}

IScannerComponents

interface IScannerComponents {
  tracker?: TrackFunction;
  onOff?: boolean;
  torch?: boolean;
  zoom?: boolean;
  finder?: boolean;
}

TrackFunction

type TrackFunction = (
  detectedCodes: IDetectedBarcode[],
  ctx: CanvasRenderingContext2D
) => void;

IScannerStyles

interface IScannerStyles {
  container?: CSSProperties;
  video?: CSSProperties;
  finderBorder?: number;
}

IScannerClassNames

interface IScannerClassNames {
  container?: string;
  video?: string;
}

Browser Support

This library requires support for:

• getUserMedia API - Camera access
• Barcode Detection API - Barcode scanning (polyfilled via barcode-detector)
• Canvas API - Drawing tracking overlays

Supported Browsers:

• Chrome/Edge 88+
• Firefox 90+ (with polyfill)
• Safari 14+ (with polyfill)
• Mobile browsers (iOS Safari 14.5+, Chrome Mobile)

The library uses webrtc-adapter for cross-browser compatibility.

Limitations

• HTTPS or localhost required - Due to browser security restrictions, camera access only works on secure contexts (HTTPS or localhost).

• iOS audio limitations - Beep sound on iOS Safari requires user interaction before playing. The first scan after page load may not play sound.

• Server-Side Rendering (SSR) - This library requires browser APIs and will not work during SSR. Ensure you only import and use it in client-side code:

  // Next.js example
  import dynamic from 'next/dynamic';
  
  const Scanner = dynamic(
    () => import('@yudiel/react-qr-scanner').then((mod) => mod.Scanner),
    { ssr: false }
  );

• Mobile browser constraints - Some mobile browsers cannot use torch and zoom simultaneously. The library automatically disables torch when zoom is activated to prevent conflicts.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © Yudiel Curbelo