@yudiel/react-qr-scanner

When integrating @yudiel/react-qr-scanner, be aware of the following constraints:

• Security: Requires HTTPS or localhost due to browser security restrictions.
• iOS Audio: The first scan after page load may not play a beep sound due to iOS user-gesture requirements.
• SSR: The library is not compatible with Server-Side Rendering; it must be loaded on the client side.
• Mobile Hardware: Some mobile browsers cannot use the torch and zoom features at the same time. The library handles this by disabling the torch when zoom is activated.

Install the package using your preferred package manager to start using the QR and barcode scanner in your React application.

npm install @yudiel/react-qr-scanner

yarn add @yudiel/react-qr-scanner

pnpm add @yudiel/react-qr-scanner

To implement a basic scanner, import the Scanner component and provide onScan and onError callbacks. The onScan callback receives the detected results, and onError handles scanning errors.

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

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

Audio on iOS

iOS Safari requires a user gesture before audio can play. The very first scan after page load might be silent; subsequent scans after user interaction will play sound normally.

Torch and Zoom

Mobile browsers cannot use ImageCapture (torch) and non-ImageCapture (zoom) constraints simultaneously. When you apply a zoom, the library automatically disables the torch. To use both, re-toggle the torch after the zoom change has settled.

If the scanner is running but not detecting codes:

• Ensure adequate lighting and camera focus.
• Try removing the formats prop to allow detection of all supported formats.
• WASM Polyfill issues: If isBarcodeDetectorSupported() is false, the library uses a WASM polyfill. If you see a 404 in the Network tab for the WASM file, you must host it correctly using prepareZXingModule({ overrides: { locateFile } }).

Because this library relies on browser-only APIs, it will fail during Server-Side Rendering (SSR). To use it in Next.js, you must import the Scanner component lazily with ssr: false.

Additionally, the useDevices() hook is browser-only and should only be called within 'use client' components or inside a dynamic wrapper.

import dynamic from 'next/dynamic';

const Scanner = dynamic(
  () => import('@yudiel/react-qr-scanner').then((m) => m.Scanner),
  { ssr: false },
);

You can restrict the scanner to specific formats using the formats prop. This accepts BarcodeFormat values (e.g., 'qr_code', 'ean_13'). You can also use shorthand values like 'linear_codes' or 'matrix_codes' to detect groups of formats.

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

The onScan callback returns an array of IDetectedBarcode objects. You can access properties like format and rawValue for each detected code.

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)}
    />
  );
}

The Scanner component is a forwardRef. You can pass a ref of type IScannerHandle to access the underlying HTMLVideoElement and the active MediaStream. This is useful for taking snapshots or manual video manipulation.

import { Scanner, type IScannerHandle } from '@yudiel/react-qr-scanner';
import { useRef } from 'react';

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

  function snapshot() {
    const video = scannerRef.current?.getVideoElement();
    if (!video) return;
    // ...take a still frame from the video element
  }

  return <Scanner ref={scannerRef} onScan={console.log} />;
}