Render to an Image Element

Use this when you need an HTMLImageElement that can be inserted into a browser page, styled with CSS, labeled for accessibility, or downloaded as a PNG.

Minimal example

1
import {ImageQRCodeRenderer} from '@qrcodesdk/browser';
2
import {qrcode} from '@qrcodesdk/core';
3

4
const image = qrcode('https://qrcodesdk.dev').render(ImageQRCodeRenderer());

The returned value is an HTMLImageElement whose src is a PNG data URL.

Common options

You can customize the image output by passing styling options to ImageQRCodeRenderer.

1
import {ImageQRCodeRenderer} from '@qrcodesdk/browser';
2
import {qrcode} from '@qrcodesdk/core';
3

4
const image = qrcode('https://qrcodesdk.dev').render(
5
  ImageQRCodeRenderer({
6
    size: 8,
7
    margin: 4,
8
    colors: {
9
      colorDark: '#111827',
10
      colorLight: '#ffffff',
11
    },
12
    alt: 'QR code for qrcodesdk.dev',
13
  }),
14
);

Option	Type	Default	Description
`size`	`number`	`5`	Pixel size of each QR module.
`margin`	`number`	`4`	Quiet-zone margin around the QR code, in modules.
`colors.colorDark`	`string`	`'#000000'`	Color used for dark QR modules.
`colors.colorLight`	`string`	`'#ffffff'`	Background color.
`alt`	`string`	`undefined`	Adds an `alt` attribute to the image.
`ariaLabel`	`string`	`undefined`	Adds an `aria-label` attribute to the image.
`title`	`string`	`undefined`	Adds a `title` attribute to the image.

Colors must be 6-digit hex values such as '#000000', '#ffffff', or '#111827'.

Image output requires size to be a positive integer and margin to be a non-negative integer.

Common recipes

Add accessibility labels

For user-facing QR codes, provide a meaningful label so assistive technologies can describe what the code points to.

1
import {ImageQRCodeRenderer} from '@qrcodesdk/browser';
2
import {qrcode} from '@qrcodesdk/core';
3

4
const image = qrcode('https://qrcodesdk.dev').render(
5
  ImageQRCodeRenderer({
6
    alt: 'QR code for qrcodesdk.dev',
7
    ariaLabel: 'Scan to open qrcodesdk.dev',
8
    title: 'QR code for qrcodesdk.dev',
9
  }),
10
);

Insert into the DOM

1
import {ImageQRCodeRenderer} from '@qrcodesdk/browser';
2
import {qrcode} from '@qrcodesdk/core';
3

4
const image = qrcode('https://qrcodesdk.dev').render(
5
  ImageQRCodeRenderer({
6
    alt: 'QR code for qrcodesdk.dev',
7
  }),
8
);
9

10
const container = document.querySelector('#qrcode');
11

12
if (container) {
13
  container.append(image);
14
}

1
<div id="qrcode"></div>

Download as PNG

Use DownloadImageQRCodeRenderer when a browser action should download the rendered image as a PNG.

1
import {DownloadImageQRCodeRenderer, ImageQRCodeRenderer} from '@qrcodesdk/browser';
2
import {qrcode} from '@qrcodesdk/core';
3

4
qrcode('https://qrcodesdk.dev').render(
5
  DownloadImageQRCodeRenderer({
6
    renderer: ImageQRCodeRenderer({
7
      alt: 'QR code for qrcodesdk.dev',
8
    }),
9
    filename: 'qrcode',
10
  }),
11
);

The download renderer appends .png when the filename does not already end with .png. It uses the wrapped image renderer’s image.src, clicks a temporary download link, and returns void.

Use the returned image element directly when you need to control the download link yourself.

1
import {ImageQRCodeRenderer} from '@qrcodesdk/browser';
2
import {qrcode} from '@qrcodesdk/core';
3

4
const image = qrcode('https://qrcodesdk.dev').render(
5
  ImageQRCodeRenderer({
6
    alt: 'QR code for qrcodesdk.dev',
7
  }),
8
);
9

10
const link = document.createElement('a');
11

12
link.href = image.src;
13
link.download = 'qrcode.png';
14
link.click();

Output details

The Image renderer generates:

A square HTMLImageElement
A PNG data URL assigned to image.src
width and height values matching the rendered QR code size
One pixel block per scaled QR module
A solid background using colors.colorLight
Dark modules using colors.colorDark
Optional alt, aria-label, and title attributes

The image renderer uses the Canvas renderer internally, then converts the canvas to a PNG data URL with canvas.toDataURL('image/png').

The final image size is calculated as:

1
const imageSize = size * (moduleCount + 2 * margin);

For example, a QR matrix with 21 modules, size: 8, and margin: 4 produces:

1
8 * (21 + 2 * 4) = 232

So the output image is 232 x 232 pixels.