Image element renderers
When to use
Section titled “When to use”Use an Image element renderer when browser code needs an HTMLImageElement with native alt
text, not a drawing surface. Choose the renderer by format:
| Renderer | Entry point | Data URL type | Encoder | Choose it for |
|---|---|---|---|---|
QRCodePNGImageRenderer |
@qrcodesdk/browser/png |
image/png |
The browser’s canvas.toDataURL() |
The default choice |
QRCodeWebPImageRenderer |
@qrcodesdk/browser/webp |
image/webp |
Bundled lossless WebP encoder | Usually the smallest file |
QRCodeGIFImageRenderer |
@qrcodesdk/browser/gif |
image/gif |
Bundled single-frame GIF encoder | Destinations that only accept GIF |
QRCodeJPEGImageRenderer |
@qrcodesdk/browser/jpeg |
image/jpeg |
Bundled baseline JPEG encoder | JPEG-only destinations, photo centers |
Each renderer has its own entry point, so your bundle only includes the encoder you import. The
root @qrcodesdk/browser entry point re-exports all four.
Minimal example
Section titled “Minimal example”import {QRCodePNGImageRenderer} from '@qrcodesdk/browser/png';import {qrcode} from '@qrcodesdk/core';
const image = qrcode('https://qrcodesdk.dev').render( QRCodePNGImageRenderer({accessibility: {alt: 'QR code: scan to open qrcodesdk.dev'}}),);The other three renderers take the same options. To insert the image into a page, see Render QR codes in the browser.
Return value
Section titled “Return value”Each renderer synchronously returns a new HTMLImageElement:
- Its
srcis a data URL, encoded from an intermediate Canvas element. - Its width and height match that Canvas backing size.
altis always set. The default empty string marks the image as decorative.
Set a meaningful alt unless nearby content already explains the QR code. Prefer alt over
ariaLabel. When both are set, assistive technology announces ariaLabel.
Options
Section titled “Options”All four renderers accept these options:
| Option | Type | Default | Effect |
|---|---|---|---|
style |
QRCodeVisualStyle |
shared defaults | Applies graphical dimensions, colors, and shapes |
accessibility.alt |
string |
'' |
Sets the Image element’s alt property |
accessibility.ariaLabel |
string |
undefined |
Sets aria-label, which overrides alt |
accessibility.title |
string |
undefined |
Sets the Image element’s title property |
centerImage |
QRCodeCanvasCenterImage |
undefined |
Draws a center image from canvasCenterImage() |
styletakes the shared visual style.centerImageworks as for the Canvas renderer.
QRCodeGIFImageRenderer adds one option:
| Option | Type | Default | Effect |
|---|---|---|---|
transparency.threshold |
integer 0–256 |
128 |
Pixels with a lower alpha value become fully transparent |
A threshold of 0 keeps every pixel opaque. 256 makes every pixel transparent.
QRCodeJPEGImageRenderer adds two options:
| Option | Type | Default | Effect |
|---|---|---|---|
quality |
integer 1–100 |
92 |
Trades file size for detail |
transparency.matte |
opaque QRCodeColor |
'#ffffff' |
Color that transparent pixels are blended onto |
Option types
Section titled “Option types”QRCodeImageRendererOptionsfrom@qrcodesdk/browser/imagedescribes the shared options.- Each format exports its own type:
QRCodePNGImageRendererOptions,QRCodeWebPImageRendererOptions,QRCodeGIFImageRendererOptions, andQRCodeJPEGImageRendererOptions. - Framework components take
QRCodePNGImageOptions,QRCodeWebPImageOptions,QRCodeGIFImageOptions, orQRCodeJPEGImageOptions. These addmatrix.
QRCodePNGImageRenderer encodes with the browser’s native canvas.toDataURL('image/png').
- PNG keeps the full alpha channel.
- It is the safest choice for transparent backgrounds and photographic center images.
QRCodeWebPImageRenderer encodes lossless WebP with an encoder bundled in the SDK.
- It also works in Safari, which cannot encode WebP natively.
- WebP keeps the full alpha channel.
- QR codes have few colors and long runs of equal pixels, so lossless WebP is usually much smaller than PNG.
The encoder produces identical bytes from identical RGBA pixels. But each browser draws the intermediate Canvas itself, and anti-aliasing of shaped modules and center images can differ. So bytes can differ between browsers.
QRCodeGIFImageRenderer encodes a single-frame GIF with an encoder bundled in the SDK. GIF has two
format limits:
- 256 colors. Images with more colors are reduced with median-cut quantization. The most frequent colors, such as the background and module colors, stay exact. Anti-aliased edges and center images may shift slightly.
- Binary transparency. Each pixel is fully transparent or opaque, decided by
transparency.threshold. Partially transparent pixels at or above the threshold become opaque, so anti-aliased edges over a transparent background look rough.
Prefer PNG or WebP for transparent backgrounds and photographic center images.
QRCodeJPEGImageRenderer encodes a baseline JPEG with an encoder bundled in the SDK. It does not
use the browser’s canvas.toDataURL('image/jpeg'), which turns transparent pixels black and encodes
differently in each browser.
- Lossy. Pixels near module edges shift slightly. The default quality is
92. Test the output with the scanners you target. - No transparency. Every pixel is blended onto
transparency.matte, white by default. - Larger files. For a plain QR code, PNG and WebP are usually smaller. JPEG pays off for photographic center images and destinations that require it.
- Grayscale output. When every pixel is gray, such as the default black-on-white style, the file stores one grayscale channel.
- Block alignment. A
style.moduleSizethat is a multiple of 8 lines modules up with JPEG’s 8 × 8 pixel blocks. Files get several times smaller. See Smaller files.
The bundled encoder produces the same bytes as the Node.js JPEG renderer for the same RGBA pixels. Browser Canvas and Node.js can anti-alias shaped modules and center images differently, though, so identical options do not guarantee identical pixels.
Constraints
Section titled “Constraints”- Synchronous rendering. Center-image sources must already be loaded and have positive intrinsic dimensions.
- Cross-origin images. Center images must be same-origin or CORS-enabled, so the Canvas can be
encoded or its pixels read. Otherwise rendering throws
QRCodeErrorwith codeRENDER_FAILED. - Option values. These throw
INVALID_OPTIONSwhen the renderer factory is called:transparency.thresholdthat is not an integer from0through256qualitythat is not an integer from1through100transparency.mattethat is not an opaque color
- Maximum size. WebP output is limited to 16,384 pixels per side. GIF and JPEG output is limited
to 65,535. Larger output throws
QRCodeErrorwith codeRENDER_FAILED. - Option copies. Renderer factories validate and copy options when they are called. The center image keeps its source by identity and checks it when rendering.
- Data URL only. The image is encoded into the element’s data URL. If the next step needs
direct drawing or
toBlob(), use the Canvas renderer.
Related guides
Section titled “Related guides”- Customize appearance for shared styling, labels, and scan reliability.
- Add a center image for preparing a
CanvasImageSource. - Render QR codes in the browser for DOM insertion and layout.
- Download or save for PNG, WebP, GIF, and JPEG downloads.
Related pages
Section titled “Related pages”Support QRCodeSDK
If you find QRCodeSDK useful, please consider sponsoring the project!