Skip to content

Canvas element renderer

Use QRCodeCanvasRenderer when browser code needs to draw, composite, inspect, or manually export raster output with the Canvas API.

For native alt text and other image attributes, use the Image element renderers instead.

import {QRCodeCanvasRenderer} from '@qrcodesdk/browser';
import {qrcode} from '@qrcodesdk/core';
const canvas = qrcode('https://qrcodesdk.dev').render(QRCodeCanvasRenderer());

To insert or composite the canvas, see Render QR codes in the browser.

import {QRCodeCanvasRenderer} from '@qrcodesdk/browser';
import {qrcode} from '@qrcodesdk/core';
import {circle, finder} from '@qrcodesdk/core/style';
const canvas = qrcode('https://qrcodesdk.dev').render(
QRCodeCanvasRenderer({
style: {moduleSize: 8, modules: circle(), finder: finder({center: circle(), color: '#2563eb'})},
}),
);

See Customize appearance for every color, shape, and finder option.

The renderer synchronously returns a new HTMLCanvasElement:

  • Width: style.moduleSize × (matrix.width + 2 × style.quietZone) pixels.
  • Height: style.moduleSize × (matrix.height + 2 × style.quietZone) pixels.
  • RGBA colors keep their alpha.

Accessibility depends on the labels you pass:

  • A non-empty ariaLabel sets role="img" and aria-label.
  • If ariaLabel is blank, a non-empty title sets them instead.
  • If both are blank, the canvas is decorative and gets aria-hidden="true".
Option Type Default Effect
style QRCodeVisualStyle shared defaults Applies graphical dimensions, colors, and shapes
accessibility.ariaLabel string undefined Sets an aria-label attribute
accessibility.title string undefined Sets a title attribute
centerImage QRCodeCanvasCenterImage undefined Draws a center image from canvasCenterImage()

style takes the shared visual style.

Create the centerImage value with canvasCenterImage(source, layout?) from @qrcodesdk/browser. The same value works for Canvas and for every Image element format.

import {QRCodeCanvasRenderer, canvasCenterImage} from '@qrcodesdk/browser';
import {qrcode} from '@qrcodesdk/core';
const logo = new Image();
logo.src = '/logo.png';
await logo.decode();
const canvas = qrcode('https://qrcodesdk.dev')
.errorCorrection('H')
.render(QRCodeCanvasRenderer({centerImage: canvasCenterImage(logo, {size: 0.3})}));
Parameter Type Default Effect
source CanvasImageSource required Loaded browser image source
layout.size number 0.3 Square image box as a fraction of the shorter matrix side
layout.padding number 1 Cleared border around the image, in modules
layout.clearBackground boolean true Removes every module the image or its padding touches

The source can be any ready CanvasImageSource, such as an HTMLImageElement, another canvas, or an ImageBitmap. The cutout follows the fitted image and its padding.

  • Synchronous rendering. The center-image source must be loaded and have positive intrinsic dimensions before rendering. Unloaded or zero-sized sources throw.
  • Center image layout. size must be finite, greater than 0, and at most 1. padding must be finite and non-negative. canvasCenterImage() validates both when it is called.
  • Option checks. TypeScript checks that centerImage comes from canvasCenterImage().
  • Option copies. QRCodeCanvasRenderer() copies option values when it is called. The center image keeps its source by identity and checks it when rendering.

Support QRCodeSDK

If you find QRCodeSDK useful, please consider sponsoring the project!