react-driving-license-scanner

React component for scanning PDF417 barcodes on US driver's licenses.

Install

npm install react-driving-license-scanner

Quick Start

import { useState } from 'react';
import { DLScanner } from 'react-driving-license-scanner';
import 'react-driving-license-scanner/styles';

function MyPage() {
  const [scanning, setScanning] = useState(false);

  return (
    <div>
      <button onClick={() => setScanning(true)}>Scan ID</button>

      {scanning && (
        <DLScanner
          onResult={(dob) => {
            console.log('Date of birth:', dob); // "YYYY-MM-DD"
            setScanning(false);
          }}
          onError={(error) => {
            console.error(error);
            setScanning(false);
          }}
        />
      )}
    </div>
  );
}

Mount the component to start scanning. Get a DOB string or error callback. Unmount to stop.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | onResult | (dob: string) => void | required | Called with "YYYY-MM-DD" when a valid DL barcode is scanned | | onError | (error: string) => void | required | Called on camera error, timeout, or user close | | timeoutMs | number | 30000 | Scan timeout in milliseconds | | showDebugPanel | boolean | false | Show debug panel with camera selection logs | | className | string | — | Custom CSS class for the outermost container | | logger | ScannerLogger | silent | Optional logger for diagnostic output |

Advanced Usage

For custom scanner UIs or non-DL barcode scanning:

import {
  useCamera,
  useBarcodeScanner,
  decodePDF417,
  parseDrivingLicense,
} from 'react-driving-license-scanner';

function CustomScanner() {
  const { videoRef, isReady, startCamera, stopCamera } = useCamera();

  useBarcodeScanner({
    videoRef,
    isReady,
    enabled: true,
    decode: decodePDF417,
    parse: parseDrivingLicense,
    onResult: (result, parsed, frame) => {
      console.log(parsed?.dateOfBirth);
    },
    onTimeout: () => console.log('Timeout'),
  });

  useEffect(() => { startCamera(); return stopCamera; }, []);

  return <video ref={videoRef} autoPlay playsInline muted />;
}

Logging

Silent by default. Pass a logger for diagnostics:

import { consoleLogger } from 'react-driving-license-scanner';

<DLScanner
  onResult={...}
  onError={...}
  logger={consoleLogger}
/>

Browser Support

| Browser | Version | Notes | |---------|---------|-------| | Chrome Android | 97+ | Full support including torch | | Safari iOS | 15+ | Camera permission not persisted in PWA | | Chrome Desktop | 97+ | Full support | | Firefox | 100+ | No torch, no focusMode | | Safari Desktop | 15.4+ | Limited camera capabilities API |

How It Works

1. Opens the device camera (selects the best back camera for barcode scanning)
2. Continuously captures video frames and decodes PDF417 barcodes using ZXing
3. Parses the AAMVA-standard barcode data to extract date of birth
4. Returns the DOB as a "YYYY-MM-DD" string via the onResult callback

Troubleshooting

• Camera not working: HTTPS is required for camera access (except localhost)
• iOS PWA: Camera permission must be re-granted each session (Apple limitation)
• Tilted barcodes: The scanner automatically tries rotations up to +/-10 degrees

License

MIT