next-qr-reader

A high-performance, React-based QR code reader component for Next.js applications.

Features

• Smooth, continuous QR code scanning
• Optimized for performance using requestAnimationFrame
• 4 beautiful UI variants with smooth animations
• Customizable detector frames and scan lines
• Customizable scan interval and camera constraints
• Optional vertical camera preview flip
• Optional horizontal camera preview flip (mirror correction)
• Programmatic camera on/off control
• Error handling with optional callback
• TypeScript support
• Easy to integrate with Next.js projects

Installation

Install the package using npm:

npm install next-qr-reader

Or using yarn:

yarn add next-qr-reader

Usage

Here's a basic example of how to use the Reader component:

import React from 'react';
import { Reader } from 'next-qr-reader';

const QRCodeScanner = () => {
  const handleResult = (result) => {
    console.log('QR Code scanned:', result);
  };

  const handleError = (error) => {
    console.error('QR Code scanning error:', error);
  };

  return (
    <Reader
      onResult={handleResult}
      onError={handleError}
      className="w-full max-w-md mx-auto"
    />
  );
};

export default QRCodeScanner;

API

Reader Component Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | onResult | (result: string) => void | Required | Callback function called when a QR code is successfully scanned | | constraints | MediaTrackConstraints | { facingMode: 'environment', width: { ideal: 640 }, height: { ideal: 480 } } | Camera constraints for getUserMedia | | className | string | '' | Additional CSS classes to apply to the component | | scanInterval | number | 120 | Minimum interval (in ms) between scan attempts | | onError | (error: Error) => void | undefined | Callback function called when an error occurs during scanning | | variant | 'default' \| 'minimal' \| 'ios' \| 'clean' | 'default' | UI style variant for the detector frame | | showFrame | boolean | true | Show/hide the detector frame overlay | | frameColor | string | 'white' | Color of the detector frame (any CSS color) | | showScanLine | boolean | true | Show/hide the animated scanning line | | flipVertical | boolean | false | Flips the camera preview vertically (helpful for mirrored UI setups) | | flipHorizontal | boolean | false | Flips the camera preview horizontally (use this when left/right movement feels mirrored) | | cameraEnabled | boolean | true | Turns camera stream and scanning loop on/off programmatically |

Advanced Usage

UI Variants

The component includes 4 beautiful UI variants with smooth animations:

iOS Variant (iPhone Camera Style)

Corner brackets with radial vignette and scanning line animation.

<Reader
  onResult={handleResult}
  variant="ios"
  frameColor="white"
/>

Minimal Variant (Clean & Subtle)

Minimalist transparent border with soft animations.

<Reader
  onResult={handleResult}
  variant="minimal"
  frameColor="white"
/>

Clean Variant (Grid Style)

Grid overlay with rounded frame, corner dots, and scan line.

<Reader
  onResult={handleResult}
  variant="clean"
  frameColor="white"
/>

Default Variant (Classic)

Simple centered square frame - original style.

<Reader
  onResult={handleResult}
  variant="default"
  frameColor="white"
/>

Customizing the Detector Frame

Control the appearance of the scanning UI:

<Reader
  onResult={handleResult}
  variant="ios"
  showFrame={true}           // Show/hide frame
  frameColor="#00ff00"       // Customize color (any CSS color)
  showScanLine={true}        // Toggle scanning animation
  className="w-full max-w-md mx-auto"
/>

Custom Camera Constraints

You can customize the camera constraints to fit your needs:

<Reader
  onResult={handleResult}
  constraints={{
    facingMode: 'user',
    width: { ideal: 1280 },
    height: { ideal: 720 }
  }}
/>

Camera On/Off + Flip Controls

Control camera lifecycle and choose the preview flip direction:

import React, { useState } from 'react';
import { Reader } from 'next-qr-reader';

const ControlledScanner = () => {
  const [cameraEnabled, setCameraEnabled] = useState(true);

  return (
    <div className="space-y-3">
      <button
        type="button"
        onClick={() => setCameraEnabled((prev) => !prev)}
      >
        {cameraEnabled ? 'Turn Camera Off' : 'Turn Camera On'}
      </button>

      <Reader
        onResult={(result) => console.log(result)}
        cameraEnabled={cameraEnabled}
        flipHorizontal={true} // keeps right/left movement natural for mirrored front camera feeds
        flipVertical={false}  // set true only if you need upside-down correction
      />
    </div>
  );
};

Error Handling

Implement custom error handling:

const handleError = (error) => {
  if (error.name === 'NotAllowedError') {
    alert('Please grant camera permission to use the QR scanner.');
  } else {
    console.error('An error occurred:', error);
  }
};

<Reader onResult={handleResult} onError={handleError} />

Browser Support

This component should work in all modern browsers that support the getUserMedia API and can run Next.js applications. However, it's always a good idea to check the specific browser requirements for your target audience.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Acknowledgements

This project uses the jsQR library for QR code detection.