@qrcodesdk/react

Live Demo

@qrcodesdk/react provides React components for rendering QR codes as inline SVG, PNG-backed Image elements, and Canvas elements.

It supports React and React DOM 18 and 19.

Install

npm install @qrcodesdk/react @qrcodesdk/core @qrcodesdk/browser

pnpm add @qrcodesdk/react @qrcodesdk/core @qrcodesdk/browser

vp

vp add @qrcodesdk/react @qrcodesdk/core @qrcodesdk/browser

deno

deno add @qrcodesdk/react @qrcodesdk/core @qrcodesdk/browser

bun

bun add @qrcodesdk/react @qrcodesdk/core @qrcodesdk/browser

yarn

yarn add @qrcodesdk/react @qrcodesdk/core @qrcodesdk/browser

Quick start

Import the components directly where you need them:

import {QRCodeCanvas, QRCodeImage, QRCodeSVG} from '@qrcodesdk/react';

export function App() {
  return (
    <>
      <QRCodeSVG data="https://qrcodesdk.dev" />
      <QRCodeImage data="https://qrcodesdk.dev" />
      <QRCodeCanvas data="https://qrcodesdk.dev" />
    </>
  );
}

Components

| Component | Output | Download support | | -------------- | ------------------------------------------- | ---------------- | | QRCodeSVG | Inline SVG inside a wrapper <div> | SVG | | QRCodeImage | PNG-backed <img> inside a wrapper <div> | PNG | | QRCodeCanvas | <canvas> inside a wrapper <div> | None |

All components accept:

| Prop | Type | Description | | ----------- | -------------------------- | ----------------------------------------------- | | data | string \| number | Required QR code payload. | | options | Component-specific options | Optional matrix and renderer configuration. | | className | string | CSS class applied to the component wrapper div. |

options supports shared matrix options such as version, mode, errorCorrectionLevel, and mask. Renderer options match the corresponding QRCodeSDK renderer:

• QRCodeSVG uses QRCodeSVGOptions.
• QRCodeImage uses QRCodeImageOptions.
• QRCodeCanvas uses QRCodeCanvasOptions.

Import QRCodeSVGOptions from @qrcodesdk/core. Import QRCodeImageOptions and QRCodeCanvasOptions from @qrcodesdk/browser.

Matrix options

The options prop combines the component's renderer options with the shared QR matrix options:

| Option | Type | Default | Description | | ---------------------- | ---------------------------------------- | --------- | ----------------------- | | mode | 'numeric' \| 'alphanumeric' \| 'octet' | Automatic | Encoding mode. | | errorCorrectionLevel | 'L' \| 'M' \| 'Q' \| 'H' | 'M' | Error correction level. | | version | 1 through 40 | Automatic | Pins the QR version. | | mask | 0 through 7 | Automatic | Pins the QR mask. |

Most applications should let the builder select the mode, version, and mask automatically.

Live examples

SVG component

import {QRCodeSVG} from '@qrcodesdk/react';

export default function QRCodeSVGExample() {
  return (
    <QRCodeSVG
      data="https://qrcodesdk.dev"
      options={{
        title: 'QR code for qrcodesdk.dev',
        ariaLabel: 'Scan to open qrcodesdk.dev',
      }}
    />
  );
}

Image component

import type {QRCodeImageOptions} from '@qrcodesdk/browser';
import {QRCodeImage} from '@qrcodesdk/react';

export default function QRCodeImageExample() {
  const options: QRCodeImageOptions = {
    size: 8,
    margin: 4,
    alt: 'QR code for qrcodesdk.dev',
    ariaLabel: 'Scan to open qrcodesdk.dev',
  };

  return <QRCodeImage data="https://qrcodesdk.dev" options={options} />;
}

Canvas component

import type {QRCodeCanvasOptions} from '@qrcodesdk/browser';
import {QRCodeCanvas} from '@qrcodesdk/react';

export default function QRCodeCanvasExample() {
  const options: QRCodeCanvasOptions = {
    size: 8,
    margin: 4,
    colors: {
      colorDark: '#111827',
      colorLight: '#ffffff',
    },
  };

  return <QRCodeCanvas data="https://qrcodesdk.dev" options={options} />;
}

PNG download

import {useRef} from 'react';

import {QRCodeImage, type QRCodeDownloadHandle} from '@qrcodesdk/react';

export default function QRCodeDownloadImageExample() {
  const qrcode = useRef<QRCodeDownloadHandle>(null);

  return (
    <div className="flex flex-col items-center">
      <QRCodeImage
        data="https://qrcodesdk.dev"
        options={{
          alt: 'QR code for qrcodesdk.dev',
        }}
        ref={qrcode}
      />
      <button
        className="btn-primary"
        onClick={() => qrcode.current?.download('qrcodesdk')}
        type="button">
        Download PNG
      </button>
    </div>
  );
}

Renderer options

| Option | Components | Type | Default | | ----------------------- | ---------- | ---------------------------- | -----------------: | | size | All | number | 5 | | margin | All | number | 4 | | colors.colorDark | All | string | '#000000' | | colors.colorLight | All | string | '#ffffff' | | dotsOptions | All | QRCodeDotsOptions | {type: 'square'} | | cornersSquareOptions | All | QRCodeCornersSquareOptions | {type: 'square'} | | cornersDotOptions | All | QRCodeCornersDotOptions | {type: 'square'} | | alt | SVG, Image | string | undefined | | ariaLabel | SVG, Image | string | undefined | | title | SVG, Image | string | undefined | | image.source | All | Renderer-specific source | undefined | | image.size | All | number | 0.4 | | image.padding | All | number | 1 | | image.clearBackground | All | boolean | true |

Color options use hash-prefixed values such as #111827. All built-in renderers require a positive safe integer size and a non-negative safe integer margin.

Module, finder-ring, and finder-center options pass through to every component. Their optional colors independently inherit colors.colorDark.

Prepared center images

Prepare browser image sources before rendering:

import {useState} from 'react';

import {QRCodeImage} from '@qrcodesdk/react';

export function QRCodeWithLogo() {
  const [logo, setLogo] = useState<HTMLImageElement>();

  async function selectLogo(file: File) {
    const source = new Image();
    const localUrl = URL.createObjectURL(file);
    source.src = localUrl;

    try {
      await source.decode();
      setLogo(source);
    } finally {
      URL.revokeObjectURL(localUrl);
    }
  }

  return (
    <>
      <input
        accept="image/*"
        type="file"
        onChange={(event) => {
          const file = event.currentTarget.files?.[0];
          if (file) void selectLogo(file);
        }}
      />
      {logo ? (
        <QRCodeImage
          data="https://qrcodesdk.dev"
          options={{errorCorrectionLevel: 'H', image: {source: logo, size: 0.3}}}
        />
      ) : null}
    </>
  );
}

Use an embedded data:image/... URL for QRCodeSVG. Components never load paths or URLs themselves, and SVG/PNG downloads include the overlay.

Download files

• QRCodeSVG exposes download(filename?) and writes an SVG file through a React ref.
• QRCodeImage exposes download(filename?) and writes a PNG file through a React ref.

import {useRef} from 'react';

import {QRCodeImage, type QRCodeDownloadHandle} from '@qrcodesdk/react';

export function QRCodeDownload() {
  const qrcode = useRef<QRCodeDownloadHandle>(null);

  return (
    <>
      <button type="button" onClick={() => qrcode.current?.download('qrcodesdk')}>
        Download PNG
      </button>
      <QRCodeImage ref={qrcode} data="https://qrcodesdk.dev" />
    </>
  );
}

The appropriate .svg or .png extension is appended when necessary.

QRCodeCanvas does not include a download method. Use QRCodeImage when you want built-in PNG download support.

Server-side rendering

QRCodeSVG produces runtime-neutral SVG and can render on the server.

QRCodeImage and QRCodeCanvas rely on browser DOM and Canvas APIs, so they skip element creation and downloads outside the browser and populate their host after hydration.

Documentation

• @qrcodesdk/react
• Customize QR Codes
• Render SVG
• Render to an Image Element
• Render to Canvas