Canvas element renderer
When to use
Section titled “When to use”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.
Minimal example
Section titled “Minimal example”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.
Styled example
Section titled “Styled example”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.
Return value
Section titled “Return value”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
ariaLabelsetsrole="img"andaria-label. - If
ariaLabelis blank, a non-emptytitlesets them instead. - If both are blank, the canvas is decorative and gets
aria-hidden="true".
Options
Section titled “Options”| 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.
Center image
Section titled “Center image”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.
Constraints
Section titled “Constraints”- 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.
sizemust be finite, greater than0, and at most1.paddingmust be finite and non-negative.canvasCenterImage()validates both when it is called. - Option checks. TypeScript checks that
centerImagecomes fromcanvasCenterImage(). - Option copies.
QRCodeCanvasRenderer()copies option values when it is called. The center image keeps its source by identity and checks it when rendering.
Related guides
Section titled “Related guides”- Customize appearance for shared styling and scan reliability.
- Add a center image for loading browser image sources.
- Render QR codes in the browser for DOM insertion and layout.
- Download or save for
toBlob()export.
Related pages
Section titled “Related pages”Support QRCodeSDK
If you find QRCodeSDK useful, please consider sponsoring the project!