Customize QR Codes

QRCodeSDK separates QR code data from renderer output. Builder options control the QR matrix, and renderer options control how that matrix looks.

Size and margin

Most visual renderers accept size and margin.

1
import {SVGQRCodeRenderer, qrcode} from '@qrcodesdk/core';
2

3
const svg = qrcode('https://qrcodesdk.dev').render(
4
  SVGQRCodeRenderer({
5
    size: 8,
6
    margin: 4,
7
  }),
8
);

size is the pixel size of each QR module for SVG, PNG, Canvas, and Image output. For terminal text, it is an integer scale factor. margin is the quiet zone around the QR code, measured in modules.

Defaults:

Option	Default	Notes
`size`	`5`	Must be a positive integer for pixels.
`margin`	`4`	Must be a non-negative integer.

Colors

SVG, PNG, Canvas, and Image renderers support colors.colorDark and colors.colorLight.

1
import {SVGQRCodeRenderer, qrcode} from '@qrcodesdk/core';
2

3
const svg = qrcode('https://qrcodesdk.dev').render(
4
  SVGQRCodeRenderer({
5
    colors: {
6
      colorDark: '#111827',
7
      colorLight: '#ffffff',
8
    },
9
  }),
10
);

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

Accessibility labels

SVG and Image renderers support accessibility attributes.

1
import {SVGQRCodeRenderer, qrcode} from '@qrcodesdk/core';
2

3
const svg = qrcode('https://qrcodesdk.dev').render(
4
  SVGQRCodeRenderer({
5
    title: 'QR code for qrcodesdk.dev',
6
    ariaLabel: 'Scan to open qrcodesdk.dev',
7
  }),
8
);

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
);

Use labels for user-facing QR codes so assistive technologies can describe the destination or action.

Error correction

The default error correction level is M.

1
import {SVGQRCodeRenderer, qrcode} from '@qrcodesdk/core';
2

3
const svg = qrcode('https://qrcodesdk.dev').errorCorrection('H').render(SVGQRCodeRenderer());

Available levels are L, M, Q, and H. Higher levels can survive more damage, but they reduce capacity and can require a larger QR version.

Version and mask

Most applications should let the builder choose the version and mask automatically.

Pin them only when you need deterministic output for a test fixture, compatibility target, or visual comparison.

1
import {SVGQRCodeRenderer, qrcode} from '@qrcodesdk/core';
2

3
const svg = qrcode('HELLO WORLD')
4
  .mode('alphanumeric')
5
  .version(1)
6
  .mask(2)
7
  .render(SVGQRCodeRenderer());

Versions range from 1 to 40. Masks range from 0 to 7.

Common recipe

1
import {SVGQRCodeRenderer, qrcode} from '@qrcodesdk/core';
2

3
const svg = qrcode('https://qrcodesdk.dev')
4
  .errorCorrection('H')
5
  .render(
6
    SVGQRCodeRenderer({
7
      size: 8,
8
      margin: 4,
9
      colors: {
10
        colorDark: '#111827',
11
        colorLight: '#ffffff',
12
      },
13
      ariaLabel: 'Scan to open qrcodesdk.dev',
14
    }),
15
  );