# @qrcodesdk/react

React components for rendering QR codes as inline SVG, PNG-backed Image elements, and Canvas elements.

## Install

<PackageManagerTabs
  packages={['@qrcodesdk/react', '@qrcodesdk/core', '@qrcodesdk/browser']}
  mode="add"
/>

## Quick start

Import the components directly where you need them:

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

## Version compatibility

| @qrcodesdk/react | React               |
| ---------------- | ------------------- |
| `0.x.x`          | `^18.0.0` `^19.0.0` |

## Components

<PackageComponents className={true} />

React passes `className` to the component's wrapper `<div>`. Use a React ref when you need a
download handle; the rendered SVG, Image, or Canvas remains inside that wrapper.

## Live examples

### SVG component

<QRCodeSVG />

### Image component

<QRCodeImage />

### Canvas component

<QRCodeCanvas />

### PNG download

<QRCodeDownloadImage />

## Center images

Load and decode a browser image first, store the resulting `HTMLImageElement` in state, and pass
it through `options.image.source`. Updating that state rerenders the component with the prepared
source. See
[Add a center image](/guides/center-images/#react) for the complete
React lifecycle.

## 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.

```tsx
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.

See [Download or save](/guides/download-or-save/#download-from-react) for SVG, PNG, and manual
Canvas downloads.

## 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.

## Shared configuration

The `options` prop combines matrix settings with the selected renderer's settings. Use the
[builder reference](/reference/builder/) for encoding, version, mask, and error correction;
[Customize output](/guides/customize/) for shared visual options; and the dedicated
[renderer references](/reference/renderers/) for output-specific options and constraints.

## Public API

```ts
import {
  type QRCodeBaseProps,
  QRCodeCanvas,
  type QRCodeCanvasProps,
  type QRCodeDownloadHandle,
  QRCodeImage,
  type QRCodeImageProps,
  QRCodeSVG,
  type QRCodeSVGProps,
} from '@qrcodesdk/react';
```