Image element renderers
When to use
Section titled “When to use”Use an Image element renderer when browser code needs a CSS-customizable, accessible
HTMLImageElement rather than a drawing surface. Choose the renderer by the encoded format:
| Renderer | Entry point | Data URL type | Encoder |
|---|---|---|---|
QRCodePNGImageRenderer |
@qrcodesdk/browser/png |
image/png |
The browser’s canvas.toDataURL() |
QRCodeWebPImageRenderer |
@qrcodesdk/browser/webp |
image/webp |
Bundled lossless WebP encoder |
QRCodeGIFImageRenderer |
@qrcodesdk/browser/gif |
image/gif |
Bundled single-frame GIF encoder |
QRCodeJPEGImageRenderer |
@qrcodesdk/browser/jpeg |
image/jpeg |
Bundled baseline JPEG encoder |
PNG is the default choice. WebP is lossless and usually the smallest file for a QR code. GIF and
JPEG suit destinations that only accept those formats, and JPEG also keeps photographic center images
small. Each renderer has its own entry point, so a bundle only includes the encoder it imports. 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: 'Scan to open qrcodesdk.dev'}}),);Swap in QRCodeWebPImageRenderer, QRCodeGIFImageRenderer, or QRCodeJPEGImageRenderer for the
other formats; they take the same options. See the Image element section of Render QR codes in the browser
for insertion and data URL examples.
Return value
Section titled “Return value”Each renderer synchronously returns a new HTMLImageElement. Its src is a data URL encoded from
an intermediate Canvas element, and its width and height match that Canvas backing size. alt is
always set and defaults to an empty string.
Renderer-specific options
Section titled “Renderer-specific options”All four renderers accept the shared visual style, a
centerImage created with canvasCenterImage() as for
the Canvas renderer, and these DOM attributes:
| Option | Type | Default | Effect |
|---|---|---|---|
accessibility.alt |
string |
'' |
Sets the Image element’s alt property |
accessibility.ariaLabel |
string |
undefined |
Sets aria-label and meaningful image semantics |
accessibility.title |
string |
undefined |
Sets the Image element’s title property |
QRCodeImageRendererOptions from @qrcodesdk/browser/image describes these shared options. Each
format also exports its own type: QRCodePNGImageRendererOptions, QRCodeWebPImageRendererOptions,
QRCodeGIFImageRendererOptions, and QRCodeJPEGImageRendererOptions. Framework components take the
matching QRCodePNGImageOptions, QRCodeWebPImageOptions, QRCodeGIFImageOptions, or
QRCodeJPEGImageOptions, which add matrix.
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 |
QRCodePNGImageRenderer encodes with the browser’s native canvas.toDataURL('image/png'). PNG keeps
the full alpha channel and is the safest choice for photographic center images and transparent
backgrounds.
QRCodeWebPImageRenderer encodes lossless WebP with an encoder bundled in the SDK, so output is the
same in every browser, including 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.
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; antialiased edges and center images may shift slightly.
- Binary transparency. A pixel is either fully transparent or opaque, decided by
transparency.threshold. Partially transparent pixels at or above the threshold become opaque, so antialiased 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. The browser’s
own canvas.toDataURL('image/jpeg') is not used, because it turns transparent pixels black and
encodes differently in each browser. The bundled encoder produces the same bytes as the Node.js
JPEG renderer for the same pixels.
- Lossy. Pixels near module edges shift slightly. The default quality of
92keeps edges sharp enough for reliable scanning. - No transparency. Every pixel is blended onto
transparency.matte, which defaults to white. - 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.
When every pixel is gray, such as the default black-on-white style, the file stores one grayscale
channel. A style.moduleSize that is a multiple of 8 lines modules up with JPEG’s 8 × 8 pixel blocks
and makes files several times smaller; see Smaller files.
Renderer-specific constraints
Section titled “Renderer-specific constraints”- Rendering is synchronous; center-image sources must already be loaded and have positive intrinsic dimensions.
- 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. - Options are validated and copied when the renderer factory is called.
transparency.thresholdmust be an integer from0through256,qualityan integer from1through100, andtransparency.mattean opaque color; other values throwINVALID_OPTIONS. The center image retains its source by identity and checks it when rendering. - WebP output is limited to 16,384 pixels per side, and GIF and JPEG output to 65,535. Larger output throws
QRCodeErrorwith codeRENDER_FAILED. - The image is encoded into the element’s data URL. Use the
Canvas renderer when the next step needs direct drawing or
toBlob()rather than an Image element.
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!