@qrcodesdk/react
React components that render QR codes as inline SVG, as PNG, WebP, GIF, or JPEG Image elements, or as Canvas elements.
Install
Section titled “Install”npm install @qrcodesdk/reactpnpm add @qrcodesdk/reactvp add @qrcodesdk/reactdeno add npm:@qrcodesdk/reactbun add @qrcodesdk/reactyarn add @qrcodesdk/reactQuick start
Section titled “Quick start”Import a component where you need it:
import {QRCodeSVG, type QRCodeSVGOptions} from '@qrcodesdk/react';
const options: QRCodeSVGOptions = { accessibility: {ariaLabel: 'Scan to open qrcodesdk.dev'},};
export function App() { return ( <figure> <QRCodeSVG payload="https://qrcodesdk.dev" options={options} /> <figcaption> Scan the code or open <a href="https://qrcodesdk.dev">qrcodesdk.dev</a> </figcaption> </figure> );}ariaLabelnames the QR code for screen readers. The link gives everyone another way to reach the destination.- Without
accessibilityoptions, the QR code is decorative and hidden from assistive technology. Leave it unlabeled only when nearby content, such as this link, already explains it. QRCodePNG,QRCodeWebP,QRCodeGIF,QRCodeJPEG, andQRCodeCanvastake the samepayloadandoptionsprops. Image components also acceptaccessibility.alt.
Version compatibility
Section titled “Version compatibility”| @qrcodesdk/react | React |
|---|---|
0.x.x |
^18.0.0 ^19.0.0 |
Components
Section titled “Components”Each output format has its own component. Your bundle only includes the encoders of the components you import.
| Component | Output | Download support |
|---|---|---|
QRCodeSVG | Inline SVG element | SVG |
QRCodePNG | PNG-backed <img> | PNG |
QRCodeWebP | WebP-backed <img> | WebP |
QRCodeGIF | GIF-backed <img> | GIF |
QRCodeJPEG | JPEG-backed <img> | JPEG |
QRCodeCanvas | <canvas> element | None |
Component props
| Prop | Type | Description |
|---|---|---|
payload | string | number | Required QR code payload. |
options | Component-specific options | Optional matrix options and renderer options, such as QRCodeSVGOptions for QRCodeSVG. |
className, style, other <div> props | ComponentPropsWithoutRef<'div'> | Passed to the wrapper <div> that contains the output element. children and dangerouslySetInnerHTML are not accepted. |
ref | Ref<QRCodeDownloadHandle> | Receives download(filename?), not the wrapper element. QRCodeCanvas does not accept a ref. |
Choose an image format
Section titled “Choose an image format”QRCodePNGuses the browser’s native PNG encoder.QRCodeWebPuses a lossless encoder bundled in the SDK. It also works in Safari and usually produces the smallest file.QRCodeGIFis limited to 256 colors and on-or-off transparency. Prefer PNG or WebP for transparent backgrounds and photographic center images.QRCodeJPEGis lossy and has no transparency. It blends transparent pixels onto a white matte by default. Itsqualityoption ranges from 1 to 100 and defaults to 92. Use it only when a destination requires JPEG.
See Image element renderers for details.
Live examples
Section titled “Live examples”SVG component
Section titled “SVG component”import {useMemo} from 'react';
import {QRCodeSVG, type QRCodeSVGOptions} from '@qrcodesdk/react';
export default function QRCodeSVGExample() { const options = useMemo<QRCodeSVGOptions>( () => ({ accessibility: { title: 'QR code for qrcodesdk.dev', ariaLabel: 'Scan to open qrcodesdk.dev', }, }), [], );
return <QRCodeSVG payload="https://qrcodesdk.dev" options={options} />;}PNG component
Section titled “PNG component”import {useMemo} from 'react';
import {QRCodePNG, type QRCodePNGImageOptions} from '@qrcodesdk/react';
export default function QRCodePNGExample() { const options = useMemo<QRCodePNGImageOptions>( () => ({ style: {moduleSize: 8, quietZone: 4}, accessibility: { alt: 'QR code: scan to open qrcodesdk.dev', }, }), [], );
return <QRCodePNG payload="https://qrcodesdk.dev" options={options} />;}WebP component
Section titled “WebP component”import {useMemo} from 'react';
import {QRCodeWebP, type QRCodeWebPImageOptions} from '@qrcodesdk/react';
export default function QRCodeWebPExample() { const options = useMemo<QRCodeWebPImageOptions>( () => ({ style: {moduleSize: 8, quietZone: 4}, accessibility: { alt: 'QR code: scan to open qrcodesdk.dev', }, }), [], );
return <QRCodeWebP payload="https://qrcodesdk.dev" options={options} />;}GIF component
Section titled “GIF component”import {useMemo} from 'react';
import {QRCodeGIF, type QRCodeGIFImageOptions} from '@qrcodesdk/react';
export default function QRCodeGIFExample() { const options = useMemo<QRCodeGIFImageOptions>( () => ({ style: {moduleSize: 8, quietZone: 4}, accessibility: { alt: 'QR code: scan to open qrcodesdk.dev', }, }), [], );
return <QRCodeGIF payload="https://qrcodesdk.dev" options={options} />;}JPEG component
Section titled “JPEG component”import {useMemo} from 'react';
import {QRCodeJPEG, type QRCodeJPEGImageOptions} from '@qrcodesdk/react';
export default function QRCodeJPEGExample() { const options = useMemo<QRCodeJPEGImageOptions>( () => ({ style: {moduleSize: 8, quietZone: 4}, quality: 90, accessibility: { alt: 'QR code: scan to open qrcodesdk.dev', }, }), [], );
return <QRCodeJPEG payload="https://qrcodesdk.dev" options={options} />;}Canvas component
Section titled “Canvas component”import {useMemo} from 'react';
import {QRCodeCanvas, type QRCodeCanvasOptions} from '@qrcodesdk/react';
export default function QRCodeCanvasExample() { const options = useMemo<QRCodeCanvasOptions>( () => ({ style: { moduleSize: 8, quietZone: 4, foreground: '#111827', background: '#ffffff', }, accessibility: {ariaLabel: 'Scan to open qrcodesdk.dev'}, }), [], );
return <QRCodeCanvas payload="https://qrcodesdk.dev" options={options} />;}PNG download
Section titled “PNG download”import {useMemo, useRef} from 'react';
import {QRCodePNG, type QRCodeDownloadHandle, type QRCodePNGImageOptions} from '@qrcodesdk/react';
export default function QRCodeDownloadPNGExample() { const qrcode = useRef<QRCodeDownloadHandle>(null); const options = useMemo<QRCodePNGImageOptions>( () => ({accessibility: {alt: 'QR code: scan to open qrcodesdk.dev'}}), [], );
return ( <> <QRCodePNG payload="https://qrcodesdk.dev" options={options} ref={qrcode} /> <button onClick={() => qrcode.current?.download('qrcodesdk')} type="button"> Download PNG </button> </> );}Center images
Section titled “Center images”For PNG, WebP, GIF, JPEG, and Canvas components:
- Load and decode a browser image.
- Store the options with
centerImage: canvasCenterImage(image)in state.
QRCodeSVG takes svgCenterImage() with an embedded data URL instead. See
Add a center image for the complete React example.
Download files
Section titled “Download files”Every component except QRCodeCanvas exposes download(filename?). Get it through a React ref.
The method appends the file extension when needed.
See Download or save for a complete React example. For manual downloads, see Export a canvas manually.
Server-side rendering
Section titled “Server-side rendering”QRCodeSVGproduces runtime-neutral SVG and renders on the server.QRCodePNG,QRCodeWebP,QRCodeGIF,QRCodeJPEG, andQRCodeCanvasneed browser DOM and Canvas APIs. On the server, they render an empty wrapper and skip downloads. They fill the wrapper after hydration.
Next.js client boundary
Section titled “Next.js client boundary”The package entry declares 'use client', so Server Components can import its components directly.
Props that cross this boundary must be serializable.
Shape path objects from @qrcodesdk/core/style, such as rounded(), can cross it. Create these
values inside a client component instead:
finder()andalignment()results, which are functions;- center images from
svgCenterImage()andcanvasCenterImage(); matrix.segmenter, includingautomaticSegmenter, which is a function.matrix.kanji, the Kanji table, which loses its identity when it is serialized.
In a Server Component, import shape factories from @qrcodesdk/core/style, not from
@qrcodesdk/react. On the server, every export of a 'use client' module is a client reference
that cannot be called.
This needs @qrcodesdk/core as a direct dependency, at the exact version that @qrcodesdk/react
depends on. Follow
Add Core to a framework project.
Mismatched copies can draw shapes incorrectly, ignore center images, and break
instanceof QRCodeError.
import {rounded} from '@qrcodesdk/core/style';import {QRCodeSVG} from '@qrcodesdk/react';
export default function Page() { return ( <QRCodeSVG payload="https://qrcodesdk.dev" options={{ style: {modules: rounded()}, accessibility: {ariaLabel: 'Scan to open qrcodesdk.dev'}, }} /> );}Client components can import every factory from @qrcodesdk/react:
'use client';
import {QRCodeSVG, type QRCodeSVGOptions, circle, finder} from '@qrcodesdk/react';
const options: QRCodeSVGOptions = {style: {finder: finder({center: circle()})}};
export function StyledQRCode() { return <QRCodeSVG payload="https://qrcodesdk.dev" options={options} />;}Shared options
Section titled “Shared options”The options prop groups encoding settings under matrix. Renderer settings, such as style,
accessibility, and centerImage, sit next to it:
import {type QRCodeSVGOptions, circle, finder, rounded} from '@qrcodesdk/react';
const options: QRCodeSVGOptions = { matrix: {errorCorrectionLevel: 'H'}, style: {moduleSize: 8, quietZone: 4, modules: rounded(), finder: finder({center: circle()})}, accessibility: {ariaLabel: 'Scan to open qrcodesdk.dev'},};Each component has its own options type:
| Component | Options type | Extra options |
|---|---|---|
QRCodeSVG |
QRCodeSVGOptions |
None |
QRCodePNG |
QRCodePNGImageOptions |
None |
QRCodeWebP |
QRCodeWebPImageOptions |
None |
QRCodeGIF |
QRCodeGIFImageOptions |
transparency.threshold |
QRCodeJPEG |
QRCodeJPEGImageOptions |
quality, transparency.matte |
QRCodeCanvas |
QRCodeCanvasOptions |
None |
Learn more about each group:
- Builder and matrix covers the fields inside
matrix. - Customize appearance covers
style. - Renderer outputs covers output-specific options.
Import payload helpers, such as wifiPayload(), from @qrcodesdk/react.
QRCodeError comes from @qrcodesdk/core. To use it,
add Core to the project.
Mixed-mode segmentation
Section titled “Mixed-mode segmentation”Mixed-mode segmentation is opt-in. Import automaticSegmenter from @qrcodesdk/react and pass it as
matrix.segmenter. The segmenter is a function, so in Next.js, create these options in a client
component:
'use client';
import {QRCodeSVG, type QRCodeSVGOptions, automaticSegmenter} from '@qrcodesdk/react';
const options: QRCodeSVGOptions = {matrix: {mode: 'auto', segmenter: automaticSegmenter}};
export function OptimizedQRCode({payload}: {payload: string}) { return <QRCodeSVG payload={payload} options={options} />;}Keep options stable
Section titled “Keep options stable”Components memoize their renderer on the identity of the options object.
- An object literal written inline in JSX is a new object on every render. The component then recreates the renderer and renders the QR code again. Image and Canvas components also re-encode and replace their element.
- Changing a property of the same object does not update the QR code. Pass a new object instead.
Define constant options outside the component. Wrap options that depend on props or state in
useMemo.
Errors
Section titled “Errors”Components throw QRCodeError for invalid payloads and options.
| Component | Where it throws |
|---|---|
QRCodeSVG |
During rendering |
| Image and Canvas components | Options during rendering, payloads in a useEffect |
To handle them:
- In the browser, place an error boundary above the component. It catches both cases.
- Error boundaries do not catch errors during server-side rendering. Validate user-controlled payloads before rendering.
- Wrap downloads called from an event handler in your own
try/catch.
See Check errors from framework packages.
Public API
Section titled “Public API”import { type QRCodeAlignmentCenterShape, type QRCodeAlignmentOptions, type QRCodeAlignmentRingShape, type QRCodeAlignmentStyle, type QRCodeBaseProps, QRCodeCanvas, type QRCodeCanvasAccessibilityOptions, type QRCodeCanvasCenterImage, type QRCodeCanvasOptions, type QRCodeCanvasProps, type QRCodeCenterImageLayout, type QRCodeCircleShapeOptions, type QRCodeColor, type QRCodeDataImageURL, type QRCodeDownloadHandle, type QRCodeEncodingMode, type QRCodeErrorCorrectionLevel, type QRCodeFinderCenterShape, type QRCodeFinderOptions, type QRCodeFinderRingShape, type QRCodeFinderStyle, QRCodeGIF, type QRCodeGIFImageOptions, type QRCodeGIFProps, type QRCodeImageAccessibilityOptions, QRCodeJPEG, type QRCodeJPEGImageOptions, type QRCodeJPEGProps, type QRCodeKanji, type QRCodeMask, type QRCodeMatrixOptions, type QRCodeMode, type QRCodeModulePattern, type QRCodeModuleShape, QRCodePNG, type QRCodePNGImageOptions, type QRCodePNGProps, type QRCodePayload, type QRCodeRoundedShapeOptions, QRCodeSVG, type QRCodeSVGAccessibilityOptions, type QRCodeSVGCenterImage, type QRCodeSVGOptions, type QRCodeSVGProps, type QRCodeSegment, type QRCodeSegmenter, type QRCodeSegmenterOptions, type QRCodeShape, type QRCodeShapePath, type QRCodeShapePiece, type QRCodeVersion, type QRCodeVisualStyle, QRCodeWebP, type QRCodeWebPImageOptions, type QRCodeWebPProps, alignment, automaticSegmenter, canvasCenterImage, circle, customShape, diagonal, finder, kanji, rounded, svgCenterImage,} from '@qrcodesdk/react';@qrcodesdk/react
- Version
- v0.0.6
- Downloads
- 714/mo
- Install size
- 800.7 kB
- Bundled size
- 35.5 kB
Related pages
Section titled “Related pages”Support QRCodeSDK
If you find QRCodeSDK useful, please consider sponsoring the project!