Skip to content

PNG Buffer renderer

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.

import {qrcode} from '@qrcodesdk/core';
import {QRCodePNGRenderer} from '@qrcodesdk/node';
const png = qrcode('https://qrcodesdk.dev').render(QRCodePNGRenderer());
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.

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.

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()
  • QRCodePNGRendererOptions accepts only these keys.
  • style and centerImage form QRCodeRasterRendererOptions, which all four Node.js renderers share.
  • Compression changes encoding effort and file size, never the QR modules. 0 disables DEFLATE compression. 9 requests the highest level.

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.

  • Compression level. compression.level must be a safe integer from 0 through 9.
  • Center image source. The source must be a Uint8Array, such as a Node.js Buffer, with valid PNG bytes. Other formats, paths, and URLs are not decoded.
  • Center image layout. size must be finite, greater than 0, and at most 1. padding must 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() throws INVALID_IMAGE_SOURCE for an invalid source and INVALID_OPTIONS for an invalid layout.
  • Option checks. TypeScript rejects unknown keys and checks that centerImage comes from rasterCenterImage(). 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.

Support QRCodeSDK

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