Versions (minVersion / maxVersion)

QR Code versions refer to the size of the output (the size will be 17 + version * 4, plus outer padding).

By default, all versions can be used. To restrict this, you can specify a minimum and/or maximum version:

const code = generate('LEAN-QR LIBRARY', {
  minVersion: 10,
  maxVersion: 20,
});

Versions must be integers in the range 1–40 (inclusive).

If there is too much data for the maxVersion size, an error will be thrown.

Correction Levels (minCorrectionLevel / maxCorrectionLevel)

QR Code correction levels control the amount of damage the QR Code can sustain before it becomes unreadable.

You can specify minimum and maximum correction levels:

const code = generate('LEAN-QR LIBRARY', {
  minCorrectionLevel: correction.M,
  maxCorrectionLevel: correction.Q,
});

generate will pick the smallest version (size) which supports the minCorrectionLevel, then within this version will use the highest possible correction level up to maxCorrectionLevel.

Generally it does not make sense to customise the maxCorrectionLevel unless you are targetting a reader which does not support a particular correction level, or you are forcing a particular level for stylistic purposes.

Masks (mask)

QR Code masks are patterns which are applied to the resulting QR Code in an effort to maximise readability for scanners (e.g. by avoiding data sections that look like a locator pattern, or large areas of the same colour). To achieve this, ISO 18004 requires that the mask is chosen according to a specific algorithm (and this is the default behaviour), but it is also possible to explicitly specify a non-optimal mask:

const code = generate('LEAN-QR LIBRARY', {
  mask: 5,
});

Valid masks are integers in the range 0–7 (inclusive).

Note that this may make your QR Code more difficult to scan, and should generally be left as the default (null).

Modes

The content you are encoding into a QR Code can be represented using a variety of "modes" (character encodings). These can be combined to achieve some amount of compression, allowing more content to fit in a smaller space.

By default, the optimal encoding mode is chosen to minimise the resulting QR Code size (this includes switching modes part way through a message if it reduces the size).

If you want to change the modes considered during this optimisation (perhaps if you are targeting a reader which does not support certain modes, or if you want to support a non-standard mode), you can specify a list of options:

const code = generate('LEAN-QR LIBRARY', {
  modes: [
    mode.numeric,
    mode.alphaNumeric,
    mode.ascii,
    mode.iso8859_1,
    // mode.shift_jis, - example: exclude Shift-JIS
    mode.utf8,
    myCustomMode, // see Custom Modes below
  ],
});

Or for full control, you can define the modes before passing the content in, avoiding the automatic optimisation entirely:

import { generate, mode } from 'lean-qr';

const code = generate(mode.alphaNumeric('LEAN-QR LIBRARY'));

Note that if you specify a mode explicitly, it is your responsibility to ensure the content you are encoding conforms to the accepted character set. If you provide mismatched content, the resulting QR Code will likely be malformed. The available modes and their supported character sets are:

There are also some meta-modes:

const code = generate(mode.multi(
  mode.iso8859_1('https://example.com/'),
  mode.numeric('123456789012345678901234567890'),
  mode.alphaNumeric('/LOOKUP'),
));

const code = generate(mode.multi(
  mode.eci(24), // Arabic (Windows-1256)
  mode.bytes([0xD3]), // Shin character
));

const code = generate(mode.multi(
  mode.auto('FOOBAR', {
    modes: [mode.numeric, mode.iso8859_1], // disallowing alphaNumeric mode
  }),
  mode.bytes([0x12, 0x34]), // finish message with non-standard custom data
));

Trailer

ISO 18004 requires 0b11101100_00010001 (0xEC11) be used as padding bytes at the end of a message, but you can customise this otherwise dead space with any 16-bit value (0x0000 – 0xFFFF).

const code = generate('LEAN-QR LIBRARY', {
  trailer: 0x0000,
});

Combining a large minVersion with a trailer of 0x0000 will reveal the pattern of the chosen mask, which may be desirable for artistic reasons. In general, this should be left as the default value to maximise readability.

.with(...modes)

Adds one or more custom modes to the list of default modes.

const myGenerate = generate.with(myCustomMode);
const code = myGenerate('text');

This is equivalent to adding the custom mode(s) to the modes argument in all calls:

const code = generate('LEAN-QR LIBRARY', {
  modes: [
    mode.numeric,
    mode.alphaNumeric,
    mode.ascii,
    mode.iso8859_1,
    mode.shift_jis,
    mode.utf8,
    myCustomMode,
  ],
});

Note that you only need to register custom modes if you want to use automatic encoding. There is no need to register a custom mode if you call it explicitly:

const code = generate(myCustomMode('FOOBAR'));

.toString([options])

Converts the QR Code to a string (e.g. for printing to the terminal)

console.log(code.toString({
  on: '##',
  off: '  ', // note: this is 2 spaces
  lf: '\n',
  padX: 4,
  padY: 4,
}));

The options shown are the defaults. Note that for portability, the defaults only use ASCII characters, but this will not result in a successful read (QR Code scanners require well-defined edges between cells). As such, if you want to print a scannable QR Code, you will need to replace at least on with an alternative value for your environment (see below).

ISO 18004 requires 4-cell padding to guarantee a successful read, but you can change it to any value if you want.

// Inverted "on" cells:
console.log(code.toString({
  on: '\u001B[7m  \u001B[0m', // ANSI escape: inverted
}));

// Or explicit black / white cells:
console.log(code.toString({
  on: '\u001B[40m  ',   // ANSI escape: black background
  off: '\u001B[107m  ', // ANSI escape: white background
  lf: '\u001B[0m\n',    // ANSI escape: default
}));

// Unicode box drawing characters: (not recommended)
console.log(code.toString({
  on: '\u2588\u2588',
}));

.toCanvas(canvas[, options])

Renders the QR Code inside an existing canvas on the page.

const targetCanvas = document.getElementById('my-canvas');
code.toCanvas(targetCanvas, {
  on: [0x00, 0x00, 0x00, 0xFF], // black
  off: [0x00, 0x00, 0x00, 0x00], // transparent
  padX: 4,
  padY: 4,
});

The options shown are the defaults.

This will replace the image in targetCanvas (which must be a <canvas> element) with a copy of the current QR Code. The result is always at a scale of 1 pixel per module (the canvas will be resized to the correct size automatically). To display this image at a reasonable size, it is recommended that you use the following CSS:

#my-canvas {
  width: 100%;
  image-rendering: pixelated;
}

The values of on and off should be arrays in [red, green, blue, alpha?] format. If alpha is omitted, 255 is assumed.

.toImageData(context[, options])

If you do not want to replace the entire content of a canvas, you can can use toImageData instead. This returns an ImageData representation of the QR Code (created using context.createImageData).

const myContext = myCanvas.getContext('2d');

const imageData = code.toImageData(myContext, {
  on: [0x00, 0x00, 0x00, 0xFF], // black
  off: [0x00, 0x00, 0x00, 0x00], // transparent
  padX: 4,
  padY: 4,
});

// later
myContext.putImageData(imageData, 200, 100);

The options shown are the defaults.

.toDataURL([options])

Returns a string which can be used as a href, e.g. for downloading;

const url = code.toDataURL({
  type: 'image/png',
  on: [0x00, 0x00, 0x00, 0xFF], // black
  off: [0x00, 0x00, 0x00, 0x00], // transparent
  padX: 4,
  padY: 4,
  scale: 1,
});

const link = document.createElement('a');
link.setAttribute('href', url);
link.setAttribute('download', 'my-qr.png');
document.body.append(link);

The options shown are the defaults. You will probably want to set scale to a larger integer as a convenience to your users.

This URL can also be used as an img source, but this is not recommended (for best results use toCanvas — this will avoid blurry edges on high resolution displays and if the user zooms in).

Note that this is only available in-browser; it will fail if called in NodeJS.

.get(x, y)

For custom output formats, you can inspect the data directly:

for (let y = 0; y < code.size; y++) {
  for (let x = 0; x < code.size; x++) {
    process.stdout.write(code.get(x, y) ? '##' : '  ');
  }
  process.stdout.write('\n');
}

Requests outside the range 0 ≤ x < size, 0 ≤ y < size will return false.

.size

An integer representing the size of the QR Code, excluding any padding. This is equal to 17 + version * 4.

toSvg(code, target[, options])

Creates or replaces an svg element with the current QR Code

import { toSvg } from 'lean-qr/extras/svg';

const mySvg = document.getElementById('my-svg');
toSvg(code, mySvg, {
  on: 'black',
  off: 'transparent',
  padX: 4,
  padY: 4,
  width: null,
  height: null,
  scale: 1,
});

The options shown are the defaults.

This will replace the image in mySvg (which must be an svg element) with a copy of the current QR Code. The result is always at a scale of 1 SVG unit per module (the viewBox will be resized to the correct size automatically). You can define a different size for the SVG element to scale the image.

If target is the document object, this will create and return a new SVG entity associated with the document (but not attached to it):

const mySvg = toSvg(code, document, {/* options */});

document.body.append(mySvg);

If width / height is given, the root SVG element will have the explicit size applied. If these are not specified, they will be auto-calculated by multiplying the QR Code size + padding by scale. You can override this for display by setting CSS properties (e.g. mySvg.style.width = '100%'; mySvg.style.height = 'auto';).

toSvgSource(code[, options])

Like toSvg but returns the source code for an SVG, rather than manipulating DOM nodes (can be called inside NodeJS).

import { toSvgSource } from 'lean-qr/extras/svg';

const svgSource = toSvgSource(code, {
  on: 'black',
  off: 'transparent',
  padX: 4,
  padY: 4,
  width: null,
  height: null,
  xmlDeclaration: false,
  scale: 1,
});

The options shown are the defaults, and match toSvg.

Returns a complete SVG document which can be written to a standalone file or included inside a HTML document.

If writing to a file, you should set xmlDeclaration to true (this prefixes the source with <?xml version="1.0" encoding="UTF-8" ?>).

toSvgDataURL(code[, options])

Like toSvg but returns a data:image/svg+xml URL containing the image data, suitable for displaying in an img tag or downloading from an a tag. Can be called inside NodeJS.

import { toSvgDataURL } from 'lean-qr/extras/svg';

const dataURL = toSvgDataURL(code, {
  on: 'black',
  off: 'transparent',
  padX: 4,
  padY: 4,
  width: null,
  height: null,
  scale: 1,
});

The options shown are the defaults, and match toSvg.

toSvgPath(code)

A raw SVG path definition for the QR Code. Used by toSvg and toSvgSource.

import { toSvgPath } from 'lean-qr/extras/svg';

const svgPath = toSvgPath(code);
// e.g. "M1 2L1 1L2 1L2 2ZM3 3L3 2L4 2L4 3Z"

The returned path is always at a scale of 1 SVG unit to 1 module, with no padding. The path will define the whole QR Code in a single string suitable for use inside <path d="[path here]">, and can be used with fill-rule of either evenodd or nonzero. The path is optimised to ensure only true edges are defined; it will not include overlapping edges (and will not have "cracks" between pixels). No other guarantees are made about the structure of this string, and the details could change in later versions.

toPngBuffer(code[, options])

Returns a Buffer containing a PNG file for the QR Code.

import { toPngBuffer } from 'lean-qr/extras/node_export';

const pngBuffer = toPngBuffer(code, {
  on: [0, 0, 0, 255],
  off: [0, 0, 0, 0],
  padX: 4,
  padY: 4,
  scale: 1,
});

The options shown are the defaults.

Returns a complete PNG Buffer which can be written to a standalone file.

toPngDataURL(code[, options])

Like toPngBuffer but returns a data:image/png URL containing the image data, suitable for displaying in an img tag or downloading from an a tag.

import { toPngDataURL } from 'lean-qr/extras/node_export';

const dataURL = toPngDataURL(code, {
  on: [0, 0, 0, 255],
  off: [0, 0, 0, 0],
  padX: 4,
  padY: 4,
  scale: 1,
});

The options shown are the defaults, and match toPngBuffer.

makeAsyncComponent(framework, generate)

Call makeAsyncComponent from the global scope (not inside a render method) to generate a component which can be rendered later:

import { generate } from 'lean-qr';
import { makeAsyncComponent } from 'lean-qr/extras/react';
import * as React from 'react';

export const QR = makeAsyncComponent(React, generate);

All the configuration options documented for generate and toCanvas can be passed to the wrapper component, plus a className for the rendered canvas:

<QR
  content="Hello!"
  minVersion={1}
  maxVersion={40}
  minCorrectionLevel={correction.L}
  maxCorrectionLevel={correction.H}
  mask={null}
  trailer={0xEC11}
  padX={4}
  padY={4}
  on={[0, 0, 0, 255]}
  off={[0, 0, 0, 0]}
  className=""
/>

The options shown are the defaults. All properties are optional except content.

The component will render to a <canvas> from a useEffect hook (this is the most performant option if the QR Code will change dynamically), but this cannot be server-side rendered (nothing will appear on the client until hydration completes). If server-side or synchronous rendering is important to you (at the expense of some performance), use makeSyncComponent instead.

You can also change the default values for the component by passing an extra argument to makeAsyncComponent. For example, if you want all QR Codes to use at least correction level H:

const QR = makeAsyncComponent(React, generate, {
  minCorrectionLevel: correction.H,
});

makeSyncComponent(framework, generate, toSvgDataURL)

Call makeSyncComponent from the global scope (not inside a render method) to generate a component which can be rendered later:

import { generate } from 'lean-qr';
import { makeSyncComponent } from 'lean-qr/extras/react';
import { toSvgDataURL } from 'lean-qr/extras/svg';
import * as React from 'react';

export const QR = makeSyncComponent(React, generate, toSvgDataURL);

All the configuration options documented for generate and toSvgDataURL can be passed to the wrapper component, plus a className for the rendered img:

<QR
  content="Hello!"
  minVersion={1}
  maxVersion={40}
  minCorrectionLevel={correction.L}
  maxCorrectionLevel={correction.H}
  mask={null}
  trailer={0xEC11}
  padX={4}
  padY={4}
  on="black"
  off="transparent"
  className=""
/>

Note: the API for this has some differences compared to makeAsyncComponent: on and off take string values for the colour, rather than arrays:

<QR content="Hello!" on="black" off="rgba(0,0,0,0)" />

The component will render to an <img> synchronously, using useMemo as an optimisation. This is not the most performant option if the code will change frequently (use makeAsyncComponent instead if that is your use-case, to avoid rendering lag), but supports server-side rendering and avoids the QR Code "flickering" when it first appears.

readError(error)

Converts errors into human-readable messages. If the error is a lean-qr library error, it will return a description rather than the code. If the error is from another library, this will extract the message property.

import { readError } from 'lean-qr/extras/errors';

try {
  const code = generate('LEAN-QR LIBRARY');
} catch (e) {
  const message = readError(e);
  window.alert(message);
}