### Local Project Setup

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/CONTRIBUTING.md

Clone the repository, navigate to the project directory, and install dependencies to set up the project locally. The `prepare` script automatically installs Husky hooks for pre-commit checks.

```bash
git clone https://github.com/yudielcurbelo/react-qr-scanner.git
cd react-qr-scanner
npm install
```

--------------------------------

### Install React QR Scanner with pnpm

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/README.md

Install the library using pnpm.

```bash
pnpm add @yudiel/react-qr-scanner
```

--------------------------------

### Install React QR Scanner with yarn

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/README.md

Install the library using yarn.

```bash
yarn add @yudiel/react-qr-scanner
```

--------------------------------

### Install React QR Scanner with npm

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/README.md

Install the library using npm.

```bash
npm install @yudiel/react-qr-scanner
```

--------------------------------

### Basic QR Scanner Setup

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/README.md

This is the most basic setup for the QR scanner. It requires importing the Scanner component and providing `onScan` and `onError` callback functions.

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

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

--------------------------------

### Basic React QR Scanner Setup

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/README.md

A minimal setup for the QR scanner component. It logs the scan result and any errors encountered.

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

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

--------------------------------

### Example: Full UI Configuration

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/configuration.md

Renders the scanner with all available UI components enabled: finder, torch, zoom, and on/off toggle.

```typescript
<Scanner
  onScan={onScan}
  components={{
    finder: true,
    torch: true,
    zoom: true,
    onOff: true,
    tracker: undefined,
  }}
/>
```

--------------------------------

### Camera Start Options (TypeScript)

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/types.md

Configure camera initialization with this interface. Specify media track constraints and whether to restart the camera if it's already active.

```typescript
interface IStartCamera {
  constraints: MediaTrackConstraints;
  restart?: boolean;
}
```

--------------------------------

### Minimal Configuration

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/configuration.md

A minimal setup where most UI components like the finder, torch, and zoom are disabled.

```typescript
<Scanner
  onScan={handleScan}
  components={{
    finder: false,
    torch: false,
    zoom: false,
    onOff: false,
  }}
/>
```

--------------------------------

### Capture Frame Example

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/types.md

Example of how to capture a frame from the scanner's video feed using the IScannerHandle. Requires importing useRef and Scanner.

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

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

  function captureFrame() {
    const video = scannerRef.current?.getVideoElement();
    if (!video) return;

    const canvas = document.createElement('canvas');
    canvas.width = video.videoWidth;
    canvas.height = video.videoHeight;
    const ctx = canvas.getContext('2d');
    if (ctx) {
      ctx.drawImage(video, 0, 0);
      console.log(canvas.toDataURL('image/png'));
    }
  }

  return (
    <>
      <Scanner ref={scannerRef} onScan={console.log} />
      <button onClick={captureFrame}>Capture</button>
    </>
  );
}
```

--------------------------------

### Custom Scanner Styles Example

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/types.md

Example demonstrating how to override default styles for the Scanner component's container and video elements using the 'styles' prop.

```jsx
<Scanner
  onScan={onScan}
  styles={{
    container: {
      borderRadius: '8px',
      boxShadow: '0 2px 8px rgba(0,0,0,0.1)',
    },
    video: {
      borderRadius: '8px',
    },
  }}
/>
```

--------------------------------

### Example: Minimal UI Configuration

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/configuration.md

Renders the scanner with only the essential UI components disabled, providing a minimal interface.

```typescript
<Scanner
  onScan={onScan}
  components={{
    finder: false,
    torch: false,
    zoom: false,
    onOff: false,
  }}
/>
```

--------------------------------

### Quick Timeout Configuration (Strict)

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/configuration.md

Use a short `startTimeoutMs` to fail quickly if the camera doesn't start. `settleDelayMs` is set low to avoid waiting for capabilities.

```typescript
<Scanner
  onScan={onScan}
  startTimeoutMs={1000}  // Fail quickly if camera doesn't start
  settleDelayMs={100}    // Don't wait for capabilities
/>
```

--------------------------------

### Basic Camera Startup with useCamera

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useCamera.md

Demonstrates how to start the camera and attach it to a video element. Ensure the component is mounted and the videoRef is available before calling startCamera. The hook handles camera initialization and provides a ready state.

```typescript
import { useRef, useEffect, useState } from 'react';
import useCamera from '@yudiel/react-qr-scanner/hooks/useCamera';

export function CameraComponent() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const camera = useCamera({ startTimeoutMs: 5000 });
  const [cameraReady, setCameraReady] = useState(false);

  useEffect(() => {
    const startCamera = async () => {
      try {
        if (!videoRef.current) return;
        await camera.startCamera(videoRef.current, {
          constraints: { facingMode: 'environment' },
        });
        setCameraReady(true);
      } catch (error) {
        console.error('Camera failed:', error);
      }
    };

    startCamera();
  }, [camera]);

  return (
    <div>
      <video ref={videoRef} autoPlay muted playsInline />
      {cameraReady && <p>Camera is ready</p>}
    </div>
  );
}
```

--------------------------------

### Start Camera Stream

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useCamera.md

Acquires a camera stream and attaches it to a video element. Requires a secure context (HTTPS or localhost).

```typescript
const videoEl = document.querySelector('video')!;
const camera = useCamera();

try {
  await camera.startCamera(videoEl, {
    constraints: {
      facingMode: 'environment',
      width: { ideal: 1280 },
      height: { ideal: 720 },
    },
  });
  console.log('Camera started. Torch supported:', camera.capabilities.torch);
} catch (error) {
  console.error('Failed to start camera:', error);
}
```

--------------------------------

### Example Detection Flow

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useScanner.md

Illustrates the sequence of events and state changes during barcode detection across multiple frames.

```text
Frame 1: Detect QR code "ABC"
  - contentBefore = {}
  - anyNewCodesDetected = true
  - onScan([{rawValue: "ABC", ...}])
  - contentBefore = {"ABC"}

Frame 2: Same QR code "ABC" visible
  - contentBefore = {"ABC"}
  - anyNewCodesDetected = false (ABC already in contentBefore)
  - onScan is NOT called
  - onFound([{ rawValue: "ABC", ...}]) called anyway for tracking

Frame 3: QR code "ABC" disappears, new code "DEF" detected
  - contentBefore = {"ABC"}
  - anyNewCodesDetected = true (DEF is new)
  - onScan([{ rawValue: "DEF", ...}])
  - onFound([{ rawValue: "DEF", ...}])
  - contentBefore = {"DEF"}

Frame 4: Code "DEF" gone, nothing detected
  - contentBefore = {"DEF"}
  - anyNewCodesDetected = false
  - onScan is NOT called
  - onFound([]) called because lastScanHadContent = true
  - contentBefore = {} (cleared because nothing detected)
```

--------------------------------

### Render Camera List using useDevices Hook

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/README.md

This example demonstrates how to use the `useDevices` hook to fetch available cameras and render them as a list. Each device is displayed with its label or a fallback identifier.

```jsx
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>
  );
}
```

--------------------------------

### startCamera

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useCamera.md

Acquires a camera stream and attaches it to a video element. It handles secure context checks, user permissions, and stream setup, returning a promise that resolves on success or rejects on failure.

```APIDOC
## startCamera(videoEl, { constraints, restart }): Promise<void>

### Description
Acquires a camera stream and attaches it to a video element.

### Parameters
#### Path Parameters
- **videoEl** (HTMLVideoElement) - Required - The video element to attach the stream to.
- **constraints** (MediaTrackConstraints) - Required - Media track constraints (e.g., `facingMode`, `deviceId`, `width`, `height`, `advanced: [{ zoom, torch }]`).
- **restart** (boolean) - Optional - If `true`, stops the current camera before starting a new one, even if constraints are identical. Default: `false`.

### Behavior
- Checks for secure context (HTTPS or localhost) before calling `getUserMedia`.
- Calls `navigator.mediaDevices.getUserMedia({ audio: false, video: constraints })`.
- Sets the stream as the `srcObject` of the video element.
- Waits for `play()` with a timeout.
- Waits `settleDelayMs` before reading capabilities and settings.
- Returns a promise that rejects if the browser lacks the Stream API, the user denies permission, or the camera is unavailable.

### Throws
- `Error` if not in a secure context
- `Error` if the Stream API is not supported
- `DOMException` (e.g., `NotAllowedError`, `NotFoundError`, `NotReadableError`, `OverconstrainedError`) mapped by `createScannerError` into an `IScannerError`
- `Error` if `play()` times out

### Example
```typescript
const videoEl = document.querySelector('video')!;
const camera = useCamera();

try {
  await camera.startCamera(videoEl, {
    constraints: {
      facingMode: 'environment',
      width: { ideal: 1280 },
      height: { ideal: 720 },
    },
  });
  console.log('Camera started. Torch supported:', camera.capabilities.torch);
} catch (error) {
  console.error('Failed to start camera:', error);
}
```
```

--------------------------------

### Start Scanning with useScanner

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useScanner.md

Initiates the barcode detection loop. Ensure you have a video element reference and define callbacks for scan results.

```typescript
const { startScanning, stopScanning } = useScanner({
  videoElementRef: videoRef,
  onScan: (codes) => console.log('Detected:', codes),
  onFound: (codes) => drawOverlay(codes),
});

startScanning(); // Begin detection
```

--------------------------------

### useCamera Hook Options Example

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/configuration.md

Customizes the behavior of the useCamera hook by adjusting timeouts for camera startup and capability settling.

```typescript
const camera = useCamera({
  startTimeoutMs: 5000,  // Allow 5 seconds for camera to start
  settleDelayMs: 1000,   // Wait longer for capabilities to settle
});
```

--------------------------------

### Configure ZXing Module Overrides

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/utilities.md

Use `prepareZXingModule` for configuration. The `setZXingModuleOverrides` function is deprecated. This example shows how to specify a custom path for locating module files.

```typescript
// Old way (deprecated)
import { setZXingModuleOverrides } from '@yudiel/react-qr-scanner';
setZXingModuleOverrides({ locateFile: (p) => `/static/${p}` });

// New way (recommended)
import { prepareZXingModule } from '@yudiel/react-qr-scanner';
prepareZXingModule({
  overrides: { locateFile: (p) => `/static/${p}` },
});
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/CONTRIBUTING.md

Follow the Conventional Commits style for commit messages. Examples include 'fix:', 'feat:', and 'test:' prefixes to categorize changes.

```git
fix: clone merged constraints before deleting facingMode
feat: forward ref on Scanner to expose video element and stream
test: cover useDevices devicechange refresh
```

--------------------------------

### Storybook Setup

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/CLAUDE.md

Configuration for Storybook, used for interactive component development. Stories are located in the `stories/` directory, utilizing React, Webpack 5, and the SWC compiler.

```javascript
// stories/ directory
// Uses React + Webpack 5 + SWC compiler
// Accessible at `http://localhost:6006` during development
```

--------------------------------

### Basic Barcode Detection with useScanner

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useScanner.md

Demonstrates the basic usage of the useScanner hook for detecting barcodes. It initializes the scanner, starts detection on component mount, and stops it on unmount. The detected codes are logged to the console.

```typescript
import { useRef, useEffect } from 'react';
import useScanner from '@yudiel/react-qr-scanner/hooks/useScanner';

export function BarcodeDetector() {
  const videoRef = useRef<HTMLVideoElement>(null);

  const { startScanning, stopScanning } = useScanner({
    videoElementRef: videoRef,
    onScan: (detectedCodes) => {
      console.log('Detected:', detectedCodes);
      detectedCodes.forEach((code) => {
        console.log(`Format: ${code.format}, Value: ${code.rawValue}`);
      });
    },
    onFound: (detectedCodes) => {
      // Called every frame when codes are visible
      // Useful for updating tracking overlays
    },
  });

  useEffect(() => {
    startScanning();
    return () => stopScanning();
  }, []);

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

--------------------------------

### Accessing Video Element and Stream via Ref

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/scanner.md

Demonstrates how to capture a snapshot of the video stream using the ref. It gets the video element, draws it onto a canvas, and converts it to a data URL.

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

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

  function captureSnapshot() {
    const video = scannerRef.current?.getVideoElement();
    if (!video) return;

    const canvas = document.createElement('canvas');
    canvas.width = video.videoWidth;
    canvas.height = video.videoHeight;
    const ctx = canvas.getContext('2d');
    if (ctx) {
      ctx.drawImage(video, 0, 0);
      const imageUrl = canvas.toDataURL('image/png');
      console.log('Snapshot:', imageUrl);
    }
  }

  return (
    <div>
      <Scanner ref={scannerRef} onScan={(result) => console.log(result)} />
      <button onClick={captureSnapshot}>Capture Snapshot</button>
    </div>
  );
}
```

--------------------------------

### Accessing the Video Element and Stream via Ref

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/scanner.md

Explains how to use `useRef` to get a reference to the `IScannerHandle` and access the underlying video element and media stream.

```APIDOC
## Accessing the Video Element and Stream

### Description
This example shows how to use a ref to access the `IScannerHandle` and retrieve the underlying video element or the active MediaStream.

### Ref Type
`IScannerHandle`

### `IScannerHandle` Methods
- `getVideoElement()`: Returns the underlying `<video>` element or `null`.
- `getStream()`: Returns the active `MediaStream` or `null`.

### Request Example
```typescript
import { Scanner, type IScannerHandle } from '@yudiel/react-qr-scanner';
import { useRef } from 'react';

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

  function captureSnapshot() {
    const video = scannerRef.current?.getVideoElement();
    if (!video) return;

    const canvas = document.createElement('canvas');
    canvas.width = video.videoWidth;
    canvas.height = video.videoHeight;
    const ctx = canvas.getContext('2d');
    if (ctx) {
      ctx.drawImage(video, 0, 0);
      const imageUrl = canvas.toDataURL('image/png');
      console.log('Snapshot:', imageUrl);
    }
  }

  return (
    <div>
      <Scanner ref={scannerRef} onScan={(result) => console.log(result)} />
      <button onClick={captureSnapshot}>Capture Snapshot</button>
    </div>
  );
}
```
```

--------------------------------

### QR Scanner with Custom Overlay

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/README.md

Enables customization of the scanning overlay by providing a `tracker` function. This example draws green bounding boxes around detected QR codes.

```typescript
import { Scanner, type TrackFunction } from '@yudiel/react-qr-scanner';

const drawBoxes: TrackFunction = (codes, ctx) => {
  codes.forEach((code) => {
    const { x, y, width, height } = code.boundingBox;
    ctx.strokeStyle = 'green';
    ctx.lineWidth = 2;
    ctx.strokeRect(x, y, width, height);
  });
};

export function App() {
  return <Scanner onScan={console.log} tracker={drawBoxes} />;
}
```

--------------------------------

### Handle ZXing WASM Load Errors

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/utilities.md

Implement error handling when calling `prepareZXingModule` to gracefully manage potential issues during WASM module loading. This example combines pre-warming and custom file location with error catching.

```typescript
import { prepareZXingModule } from '@yudiel/react-qr-scanner';

try {
  await prepareZXingModule({
    fireImmediately: true,
    overrides: {
      locateFile: (path) => `/static/wasm/${path}`,
    },
  });
  console.log('WASM ready');
} catch (error) {
  console.error('Failed to load WASM:', error);
}
```

--------------------------------

### Scanner Component Performance Tuning

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/configuration.md

Examples of configuring the Scanner component with different retryDelay values to balance performance and responsiveness. Lower values provide more frequent checks.

```jsx
// CPU-efficient: check every 500 ms
<Scanner retryDelay={500} onScan={onScan} />

// Responsive: check every 50 ms
<Scanner retryDelay={50} onScan={onScan} tracker={drawOverlay} />

// Real-time: check every 16 ms (~60 fps)
<Scanner retryDelay={16} onScan={onScan} tracker={drawOverlay} />
```

--------------------------------

### Permission Recovery for React QR Scanner

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/errors.md

Handle 'permission-denied' errors by guiding the user on how to recover camera access. This involves informing the user and providing a way to re-initiate the permission request.

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

export function PermissionAwareScanner() {
  const [isPermissionDenied, setIsPermissionDenied] = useState(false);
  const devices = useDevices();

  function handleError(err: IScannerError) {
    if (err.kind === 'permission-denied') {
      setIsPermissionDenied(true);
    }
  }

  function requestPermissionAgain() {
    setIsPermissionDenied(false);
    // Remounting Scanner will trigger getUserMedia again
  }

  return (
    <div>
      {isPermissionDenied ? (
        <div>
          <p>Camera permission is required to scan QR codes.</p>
          <ol>
            <li>Open browser settings</li>
            <li>Find this website in Permissions</li>
            <li>Change Camera from "Blocked" to "Allow"</li>
          </ol>
          <button onClick={requestPermissionAgain}>Try Again</button>
        </div>
      ) : (
        <Scanner
          onScan={(result) => console.log('Scanned:', result)}
          onError={handleError}
        />
      )}
    </div>
  );
}
```

--------------------------------

### Camera Constraints Configuration

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/README.md

Customizes the camera's behavior using `MediaTrackConstraints`. This example sets the facing mode to 'environment' (rear camera) and enforces a square aspect ratio, with ideal resolution settings.

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

--------------------------------

### Specific Format Detection with Rate Limiting and Custom Sound

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useScanner.md

Configures the useScanner hook to detect only QR codes, use a custom sound for detection, disable multiple detections, and set a longer `retryDelay` for performance. This setup is suitable for scenarios where only QR codes are expected and CPU usage should be minimized.

```typescript
import { useRef, useEffect } from 'react';
import useScanner from '@yudiel/react-qr-scanner/hooks/useScanner';

export function QRCodeScanner() {
  const videoRef = useRef<HTMLVideoElement>(null);

  const { startScanning, stopScanning } = useScanner({
    videoElementRef: videoRef,
    onScan: (detectedCodes) => {
      console.log('QR Code found:', detectedCodes[0].rawValue);
    },
    onFound: () => {}, // Unused, no tracking overlay
    formats: ['qr_code'],
    sound: 'data:audio/mp3;base64,...', // Custom sound
    allowMultiple: false,
    retryDelay: 500, // Check every 500ms to save CPU
  });

  useEffect(() => {
    startScanning();
    return () => stopScanning();
  }, []);

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

--------------------------------

### Scanner with Tracker Overlay Integration

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useScanner.md

Integrates the useScanner hook with a canvas element to draw a tracker overlay on detected barcodes. This example utilizes the `onFound` callback to draw bounding boxes around detected codes in real-time. It also configures `retryDelay` to approximately 30 frames per second for smooth tracking.

```typescript
import { useRef, useEffect } from 'react';
import useScanner from '@yudiel/react-qr-scanner/hooks/useScanner';

export function ScannerWithTracker() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);

  const { startScanning, stopScanning } = useScanner({
    videoElementRef: videoRef,
    onScan: (detectedCodes) => {
      console.log('New codes detected:', detectedCodes);
    },
    onFound: (detectedCodes) => {
      // Draw on every frame
      if (!canvasRef.current) return;
      const ctx = canvasRef.current.getContext('2d');
      if (!ctx) return;

      ctx.clearRect(0, 0, canvasRef.current.width, canvasRef.current.height);

      for (const code of detectedCodes) {
        const { boundingBox } = code;
        ctx.strokeStyle = 'green';
        ctx.lineWidth = 2;
        ctx.strokeRect(boundingBox.x, boundingBox.y, boundingBox.width, boundingBox.height);
      }
    },
    retryDelay: 33, // ~30 fps for smooth tracking
  });

  useEffect(() => {
    startScanning();
    return () => stopScanning();
  }, []);

  return (
    <div style={{ position: 'relative' }}>
      <video ref={videoRef} autoPlay muted playsInline style={{ width: '100%' }} />
      <canvas
        ref={canvasRef}
        style={{ position: 'absolute', top: 0, left: 0, width: '100%' }}
      />
    </div>
  );
}
```

--------------------------------

### Example TrackFunction: Draw Bounding Boxes

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/types.md

An example implementation of TrackFunction that draws green bounding boxes around detected barcodes on the canvas.

```typescript
const drawBoundingBoxes: TrackFunction = (detectedCodes, ctx) => {
  ctx.strokeStyle = '#00FF00';
  ctx.lineWidth = 2;

  for (const code of detectedCodes) {
    const { x, y, width, height } = code.boundingBox;
    ctx.strokeRect(x, y, width, height);
  }
};
```

--------------------------------

### Internal Camera Start Task Result (TypeScript)

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/types.md

This interface defines the structure of the result object for internal camera start operations. It is not intended for direct external use.

```typescript
interface IStartTaskResult {
  type: 'start';
  data: {
    videoEl: HTMLVideoElement;
    stream: MediaStream;
    constraints: MediaTrackConstraints;
  };
}
```

--------------------------------

### prepareZXingModule() Utility

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/README.md

The `prepareZXingModule` utility allows advanced customization of the ZXing detection engine used by the polyfill. Developers can use this to specify custom WASM loading paths or pre-warm the engine for faster initial scans.

```APIDOC
## prepareZXingModule(options)

### Description
Allows advanced customization of the ZXing detection engine used by the polyfill. Developers can use this to specify custom WASM loading paths or pre-warm the engine for faster initial scans.

### Usage
```ts
import { prepareZXingModule } from '@yudiel/react-qr-scanner';

// Override where the polyfill loads its WASM from
prepareZXingModule({
  overrides: {
    locateFile: (path) => `/static/${path}`,
  },
});

// Or pre-warm the engine before the first scan
await prepareZXingModule({ fireImmediately: true });
```

### Deprecated Alias
A `setZXingModuleOverrides` re-export is also available but **deprecated** — `setZXingModuleOverrides(x)` is equivalent to `prepareZXingModule({ overrides: x })`.

See the [`barcode-detector` docs](https://github.com/Sec-ant/barcode-detector) for the full API.
```

--------------------------------

### Build Library Commands

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/CLAUDE.md

Commands to build the React QR scanner library. Use 'npm run build' for both CJS and ESM bundles, or specific commands for individual formats.

```bash
npm run build

# Build ESM only
npm run build:esm

# Build CJS only
npm run build:cjs

# Run Storybook for development
npm run storybook

# Build Storybook for deployment
npm run build-storybook

# Lint and format with Biome
npm run biome:lint
npm run biome:check
```

--------------------------------

### Get Current Media Stream

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useCamera.md

Returns the current MediaStream object if a camera is active, otherwise returns null.

```typescript
const camera = useCamera();
const stream = camera.getStream();
if (stream) {
  console.log('Tracks:', stream.getTracks().length);
}
```

--------------------------------

### prepareZXingModule Utility

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/README.md

Asynchronously prepares the ZXing module, which might be required for certain scanning functionalities or polyfills.

```APIDOC
## prepareZXingModule Utility

### Description
This utility function asynchronously loads and initializes the ZXing library, which can be used as a fallback or for specific barcode formats. It accepts configuration options.

### Usage
```javascript
import { prepareZXingModule } from 'react-qr-scanner';

async function initializeScanner() {
  await prepareZXingModule({ /* options */ });
  console.log('ZXing module prepared.');
}
```

### Options
- `options` (object): Configuration object for the ZXing module. Structure depends on ZXing integration.
```

--------------------------------

### Production-Ready Configuration

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/configuration.md

A comprehensive configuration for production use, including error handling, specific camera constraints, supported formats, UI components, styling, sound, and adjusted timeouts.

```typescript
<Scanner
  onScan={handleScan}
  onError={handleError}
  constraints={{
    facingMode: 'environment',
    width: { ideal: 720 },
    height: { ideal: 720 },
  }}
  formats={['qr_code', 'ean_13', 'code_128']}
  components={{
    finder: true,
    torch: true,
    zoom: true,
  }}
  styles={{
    container: {
      borderRadius: '8px',
      overflow: 'hidden',
    },
  }}
  sound={true}
  startTimeoutMs={5000}
  settleDelayMs={800}
/>
```

--------------------------------

### useScanner Hook Signature

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useScanner.md

The function signature for the useScanner hook. It takes an object of IUseScannerProps and returns functions to start and stop scanning.

```typescript
export default function useScanner(props: IUseScannerProps) {
  // returns: {
  //   startScanning: () => void;
  //   stopScanning: () => void;
  // }
}
```

--------------------------------

### Accessing Scanner Ref

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/scanner.md

Use `useRef` to get a reference to the Scanner component. This allows access to methods like `getVideoElement` and `getStream` for advanced control.

```typescript
const scannerRef = useRef<IScannerHandle>(null);
<Scanner ref={scannerRef} onScan={onScan} />
```

```typescript
interface IScannerHandle {
  getVideoElement: () => HTMLVideoElement | null;
  getStream: () => MediaStream | null;
}
```

--------------------------------

### Common Development Commands

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/CONTRIBUTING.md

Execute these commands for various development tasks. Use `npm run storybook` for visual development, `npm run build` to compile the library, `npm run biome:check` or `npm run biome:lint` for code formatting and linting, `npm run typecheck` for TypeScript checks, and `npm test` for running tests.

```bash
# Run Storybook (visual development environment)
npm run storybook

# Build the library (CJS + ESM + .d.ts)
npm run build

# Lint and format with Biome
npm run biome:check    # writes fixes
npm run biome:lint     # lint only

# Type-check
npm run typecheck

# Tests
npm test               # one-shot
npm run test:watch     # watch mode
npm run test:coverage  # with coverage report

# Bundle size check (after `npm run build`)
npm run size
```

--------------------------------

### prepareZXingModule Utility

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/README.md

Asynchronously prepares the ZXing module, which is likely used for barcode decoding. Requires options for configuration.

```typescript
export function prepareZXingModule(options: { /* ... */ }): Promise<void>;
```

--------------------------------

### Pre-warm ZXing WASM Engine

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/utilities.md

Call `prepareZXingModule` with `fireImmediately: true` to pre-warm the ZXing engine. This is useful for measuring and optimizing the initialization time of the WASM module.

```typescript
import { prepareZXingModule } from '@yudiel/react-qr-scanner';

const startTime = performance.now();

await prepareZXingModule({ fireImmediately: true });

const endTime = performance.now();
console.log(`WASM loaded in ${endTime - startTime}ms`);
```

--------------------------------

### Display Available Cameras with useDevices

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useDevices.md

Fetches and lists all available camera devices. Useful for displaying a count or a list of cameras to the user.

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

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

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

--------------------------------

### Get Available Video Devices with useDevices Hook

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/README.md

The `useDevices` hook returns an array of available video input devices, such as cameras. This is useful for listing camera options to the user.

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

--------------------------------

### Specify QR Code, EAN-13, and Code-128 Formats

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/README.md

Use the 'formats' prop to filter detection to specific barcode types. This example restricts scanning to QR codes, EAN-13, and Code-128.

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

--------------------------------

### IUseCameraOptions

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/types.md

Options object for configuring the `useCamera()` hook. Allows customization of timeouts and delays for camera initialization.

```APIDOC
## IUseCameraOptions

Options object for `useCamera()`.

```typescript
interface IUseCameraOptions {
  startTimeoutMs?: number;
  settleDelayMs?: number;
}
```

### Fields:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `startTimeoutMs` | `number` | `3000` | Maximum time (ms) to wait for `video.play()` to resolve. |
| `settleDelayMs` | `number` | `500` | Delay (ms) after `play()` before reading capabilities. |

**Used by:**

- `useCamera()` parameter
```

--------------------------------

### Combining Multiple Overlays

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/utilities.md

Demonstrates how to chain multiple overlay functions to create a custom tracker for the Scanner component.

```APIDOC
## Combining Multiple Overlays

### Description
You can chain overlays by creating a custom tracker function that calls multiple overlay functions sequentially.

### Usage
```typescript
import { Scanner, outline, boundingBox, centerText } from '@yudiel/react-qr-scanner';

function allOverlays(detectedCodes, ctx) {
  outline(detectedCodes, ctx);
  boundingBox(detectedCodes, ctx);
  centerText(detectedCodes, ctx);
}

<Scanner onScan={onScan} tracker={allOverlays} />
```
```

--------------------------------

### Accessing Scanner Video Element and Stream via Ref

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/README.md

Use `useRef` to get a reference to the Scanner component and access its methods like `getVideoElement` and `getStream` to interact with the video feed.

```tsx
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} />;
```

--------------------------------

### Customize ZXing Module Loading

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/README.md

The `prepareZXingModule` function allows customization of how the ZXing WASM module is loaded by the polyfill. You can override file location or pre-warm the engine.

```typescript
import { prepareZXingModule } from '@yudiel/react-qr-scanner';

// Override where the polyfill loads its WASM from
prepareZXingModule({
  overrides: {
    locateFile: (path) => `/static/${path}`,
  },
});

// Or pre-warm the engine before the first scan
await prepareZXingModule({ fireImmediately: true });
```

--------------------------------

### High-Performance Overlay Configuration

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/configuration.md

Optimized for performance with a low `retryDelay` for smooth tracker updates (~30 fps). `allowMultiple` is disabled and sound is turned off to reduce latency.

```typescript
<Scanner
  onScan={handleScan}
  onError={handleError}
  tracker={drawBoundingBoxes}
  retryDelay={33}  // ~30 fps for smooth updates
  allowMultiple={false}
  sound={false}    // Disable sound for lower latency
/>
```

--------------------------------

### QR Scanner with Built-in UI Controls

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/scanner.md

Enable built-in UI controls for the scanner, including finder, torch, zoom, and on/off toggles. The `sound` prop can also be enabled.

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

export function ScannerWithControls() {
  return (
    <Scanner
      onScan={(result) => console.log(result)}
      components={{
        finder: true,
        torch: true,
        zoom: true,
        onOff: true,
      }}
      sound={true}
    />
  );
}
```

--------------------------------

### Example Usage of Scanner Class Names (React)

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/types.md

Apply custom CSS classes to the scanner component by passing an object conforming to IScannerClassNames to the `classNames` prop. Ensure corresponding CSS rules are defined.

```jsx
<Scanner
  onScan={onScan}
  classNames={{
    container: 'my-scanner-container',
    video: 'my-scanner-video',
  }}
/>
```

--------------------------------

### Scanner with Built-in UI Controls

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/scanner.md

Demonstrates enabling built-in UI elements for the scanner, such as a finder, torch, zoom, and on/off switch.

```APIDOC
## Scanner with Built-in UI Controls

### Description
This example shows how to enable and configure built-in UI controls for the scanner, including finder, torch, zoom, and power buttons.

### Props
- `components` (object): An object to configure the visibility of built-in UI components.
  - `finder` (boolean): Show the finder overlay.
  - `torch` (boolean): Show the torch toggle button.
  - `zoom` (boolean): Show the zoom control.
  - `onOff` (boolean): Show the on/off button.
- `sound` (boolean): Play a sound when a QR code is detected.

### Request Example
```typescript
import { Scanner } from '@yudiel/react-qr-scanner';

export function ScannerWithControls() {
  return (
    <Scanner
      onScan={(result) => console.log(result)}
      components={{
        finder: true,
        torch: true,
        zoom: true,
        onOff: true,
      }}
      sound={true}
    />
  );
}
```
```

--------------------------------

### Handle IScannerError in React Component

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/types.md

Provides an example of how to handle IScannerError within a React component using a switch statement on the error 'kind'. This pattern is used with the Scanner component's onError prop.

```typescript
function handleError(error: IScannerError) {
  switch (error.kind) {
    case 'permission-denied':
      console.error('Camera permission denied');
      break;
    case 'no-camera':
      console.error('No camera found');
      break;
    case 'overconstrained':
      console.error('Camera constraints not supported:', error.message);
      break;
    default:
      console.error(`Unexpected error: ${error.kind} - ${error.message}`);
  }
}

<Scanner onScan={onScan} onError={handleError} />
```

--------------------------------

### Device Enumeration and Selection with useCamera

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useCamera.md

Enables selecting between multiple available cameras. It enumerates video input devices, populates a select dropdown, and allows switching the active camera using `stopCamera` and `startCamera` with specific device constraints.

```typescript
import { useRef, useEffect, useState } from 'react';
import useCamera from '@yudiel/react-qr-scanner/hooks/useCamera';

export function DeviceSelector() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const camera = useCamera();
  const [devices, setDevices] = useState<MediaDeviceInfo[]>([]);
  const [selectedId, setSelectedId] = useState('');

  useEffect(() => {
    const enumerate = async () => {
      const all = await navigator.mediaDevices.enumerateDevices();
      const videos = all.filter((d) => d.kind === 'videoinput');
      setDevices(videos);
      if (videos.length > 0 && !selectedId) {
        setSelectedId(videos[0].deviceId);
      }
    };

    enumerate();
  }, [selectedId]);

  const switchCamera = async (deviceId: string) => {
    try {
      if (!videoRef.current) return;
      await camera.stopCamera();
      await camera.startCamera(videoRef.current, {
        constraints: { deviceId: { exact: deviceId } },
      });
      setSelectedId(deviceId);
    } catch (error) {
      console.error('Switch failed:', error);
    }
  };

  return (
    <div>
      <select value={selectedId} onChange={(e) => switchCamera(e.target.value)}>
        {devices.map((device) => (
          <option key={device.deviceId} value={device.deviceId}>
            {device.label || `Camera ${device.deviceId}`}
          </option>
        ))}
      </select>
      <video ref={videoRef} autoPlay muted playsInline />
    </div>
  );
}
```

--------------------------------

### Scanner with Device Selection

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/scanner.md

Explains how to allow users to select a specific camera device for scanning using the `useDevices` hook.

```APIDOC
## Scanner with Device Selection

### Description
This example demonstrates how to use the `useDevices` hook to list available cameras and allow the user to select one for scanning.

### Props
- `constraints` (object): MediaStream constraints to specify camera properties, including `deviceId`.

### Request Example
```typescript
import { Scanner, useDevices } from '@yudiel/react-qr-scanner';
import { useState } from 'react';

export function ScannerWithDeviceSelection() {
  const devices = useDevices();
  const [selectedDeviceId, setSelectedDeviceId] = useState('');

  return (
    <div>
      <select
        value={selectedDeviceId}
        onChange={(e) => setSelectedDeviceId(e.target.value)}
      >
        <option value="">Default 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: selectedDeviceId ? { exact: selectedDeviceId } : undefined,
        }}
      />
    </div>
  );
}
```
```

--------------------------------

### Multi-Camera Comparison with useDevices

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/useDevices.md

This snippet shows how to use the useDevices hook to find and select front and back cameras. It allows users to switch between them for scanning.

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

export function DualCameraComparison() {
  const devices = useDevices();
  const [activeTab, setActiveTab] = useState<'front' | 'back'>('back');

  const frontCamera = devices.find((d) => d.label?.toLowerCase().includes('front'));
  const backCamera = devices.find((d) => d.label?.toLowerCase().includes('back'));

  return (
    <div>
      <div style={{ display: 'flex', gap: '10px' }}>
        <button
          onClick={() => setActiveTab('back')}
          style={{ fontWeight: activeTab === 'back' ? 'bold' : 'normal' }}
        >
          Back Camera
        </button>
        <button
          onClick={() => setActiveTab('front')}
          style={{ fontWeight: activeTab === 'front' ? 'bold' : 'normal' }}
        >
          Front Camera
        </button>
      </div>

      {activeTab === 'back' && backCamera && (
        <Scanner
          onScan={(result) => console.log('Back camera scanned:', result)}
          constraints={{ deviceId: { exact: backCamera.deviceId } }}
        />
      )}

      {activeTab === 'front' && frontCamera && (
        <Scanner
          onScan={(result) => console.log('Front camera scanned:', result)}
          constraints={{ deviceId: { exact: frontCamera.deviceId } }}
        />
      )}

      {!backCamera && activeTab === 'back' && <p>No back camera found</p>}
      {!frontCamera && activeTab === 'front' && <p>No front camera found</p>}
    </div>
  );
}
```

--------------------------------

### Scanner with Custom Styles and Classes

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/scanner.md

Shows how to apply custom CSS styles and class names to the scanner's container and video elements.

```APIDOC
## Scanner with Custom Styles and Classes

### Description
This example demonstrates how to customize the appearance of the scanner component by applying inline styles and CSS classes.

### Props
- `styles` (object): An object to apply inline styles to the scanner's internal elements.
  - `container` (object): Styles for the main container.
  - `video` (object): Styles for the video element.
- `classNames` (object): An object to apply CSS classes to the scanner's internal elements.
  - `container` (string): Class name for the main container.
  - `video` (string): Class name for the video element.

### Request Example
```typescript
import { Scanner } from '@yudiel/react-qr-scanner';

export function StyledScanner() {
  return (
    <Scanner
      onScan={(result) => console.log(result)}
      styles={{
        container: {
          backgroundColor: '#1a1a1a',
          borderRadius: '8px',
        },
        video: {
          borderRadius: '8px',
        },
      }}
      classNames={{
        container: 'scanner-container',
        video: 'scanner-video',
      }}
    />
  );
}
```
```

--------------------------------

### Basic Scanner Usage

Source: https://github.com/yudielcurbelo/react-qr-scanner/blob/main/_autodocs/api-reference/scanner.md

Demonstrates the fundamental usage of the Scanner component, including how to handle scan results and errors.

```APIDOC
## Basic Scanner

### Description
This example shows how to integrate the `Scanner` component into your React application to detect and process QR codes.

### Props
- `onScan` (function): Callback function that receives an array of detected codes.
- `onError` (function): Callback function that receives error details.

### Request Example
```typescript
import { Scanner } from '@yudiel/react-qr-scanner';

export function BasicScanner() {
  return (
    <Scanner
      onScan={(result) => {
        console.log('Detected codes:', result);
        result.forEach(code => {
          console.log(`Format: ${code.format}, Value: ${code.rawValue}`);
        });
      }}
      onError={(error) => {
        console.error('Scanner error:', error.kind, error.message);
      }}
    />
  );
}
```
```