PNG Buffer renderer
When to use
Section titled “When to use”Use QRCodePNGRenderer when Node.js-compatible code needs PNG bytes: for a file, HTTP response,
attachment, object store, or another binary API.
PNG is the most widely supported raster format. It is also the safer choice for email, where SVG support varies between clients.
- For smaller files, use the WebP Buffer renderer.
- For destinations that only accept GIF or JPEG, use the GIF or JPEG Buffer renderer.
Minimal example
Section titled “Minimal example”import {qrcode} from '@qrcodesdk/core';import {QRCodePNGRenderer} from '@qrcodesdk/node';
const png = qrcode('https://qrcodesdk.dev').render(QRCodePNGRenderer());Styled example
Section titled “Styled example”import {qrcode} from '@qrcodesdk/core';import {diagonal, finder} from '@qrcodesdk/core/style';import {QRCodePNGRenderer} from '@qrcodesdk/node';
const png = qrcode('https://qrcodesdk.dev').render( QRCodePNGRenderer({ style: { moduleSize: 8, modules: diagonal(), finder: finder({ring: diagonal(), color: '#7c3aed'}), }, }),);See Customize appearance for every color, shape, and finder option.
Return value
Section titled “Return value”The renderer synchronously returns a Node.js Buffer with a complete PNG file:
- Width:
style.moduleSize × (matrix.width + 2 × style.quietZone)pixels. - Height:
style.moduleSize × (matrix.height + 2 × style.quietZone)pixels. - Shaped edges are anti-aliased.
- RGBA colors keep their alpha.
Output above 8192 × 8192 pixels (67,108,864 pixels) throws QRCodeError with code
INVALID_OPTIONS before any pixels are allocated.
Options
Section titled “Options”| Option | Type | Default | Effect |
|---|---|---|---|
style |
QRCodeVisualStyle |
shared defaults | Applies graphical dimensions, colors, and shapes |
compression.level |
integer 0–9 |
9 |
Sets the PNG DEFLATE compression level |
centerImage |
QRCodeRasterCenterImage |
undefined |
Draws a center image from rasterCenterImage() |
QRCodePNGRendererOptionsaccepts only these keys.styleandcenterImageformQRCodeRasterRendererOptions, which all four Node.js renderers share.- Compression changes encoding effort and file size, never the QR modules.
0disables DEFLATE compression.9requests the highest level.
Center image
Section titled “Center image”Create the centerImage value with rasterCenterImage(source, layout?) from @qrcodesdk/node. It
validates and decodes the PNG bytes once. Reuse one center image for many renders, in PNG, WebP,
GIF, and JPEG.
import {readFile} from 'node:fs/promises';
import {qrcode} from '@qrcodesdk/core';import {QRCodePNGRenderer, rasterCenterImage} from '@qrcodesdk/node';
const centerImage = rasterCenterImage(await readFile('./logo.png'), {size: 0.3});const png = qrcode('https://qrcodesdk.dev') .errorCorrection('H') .render(QRCodePNGRenderer({centerImage}));| Parameter | Type | Default | Effect |
|---|---|---|---|
source |
Uint8Array |
required | PNG bytes, such as a Node.js Buffer |
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 image keeps its aspect ratio and is composited with alpha. It fits inside the configured square without cropping. The cutout follows the fitted image and its padding.
Constraints
Section titled “Constraints”- Compression level.
compression.levelmust be a safe integer from0through9. - Center image source. The source must be a
Uint8Array, such as a Node.jsBuffer, with valid PNG bytes. Other formats, paths, and URLs are not decoded. - Center image layout.
sizemust be finite, greater than0, and at most1.paddingmust be finite and non-negative.rasterCenterImage()validates both when it is called. - Center image limits. The PNG may be at most 16 MiB and 16,777,216 pixels.
- Center image errors.
rasterCenterImage()throwsINVALID_IMAGE_SOURCEfor an invalid source andINVALID_OPTIONSfor an invalid layout. - Option checks. TypeScript rejects unknown keys and checks that
centerImagecomes fromrasterCenterImage(). The renderer does not repeat these checks at runtime. - Option copies.
QRCodePNGRenderer()copies option values when it is called.rasterCenterImage()decodes the image when it is called, so later changes to the source bytes have no effect.
Related guides
Section titled “Related guides”- Customize appearance for shared styling and scan reliability.
- Add a center image for reading and sizing a PNG center image.
- Download or save for writing the
Bufferto disk. - Serve a QR code for
image/pngHTTP responses.
Related pages
Section titled “Related pages”Support QRCodeSDK
If you find QRCodeSDK useful, please consider sponsoring the project!