Builder and matrix

qrcode() creates an immutable builder from @qrcodesdk/core. Each configuration method returns a new builder; the original builder remains unchanged.

Input data

The builder accepts a string or a non-negative safe integer. Use a string for values with leading zeroes or values outside JavaScript’s safe-integer range.

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

3
qrcode('https://qrcodesdk.dev');
4
qrcode(1234567890);
5
qrcode().data('data supplied later');

QRCodeSDK generates QR Code Model 2 symbols. It supports numeric, alphanumeric, and UTF-8 octet data, including automatic mixed-mode segmentation.

Encoding modes

Mode	Accepted data	Use it for
`numeric`	Digits only	Numeric identifiers and digit-only payloads
`alphanumeric`	QR alphanumeric character set	Uppercase text such as `HELLO WORLD`
`octet`	UTF-8 bytes	URLs, JSON, emoji, lowercase, and general text
omitted	Any supported input	Automatic shortest-bit segmentation; default

Setting a mode forces the complete payload into that mode. When mode is omitted, the builder splits the payload into the shortest-bit combination of numeric, alphanumeric, and octet segments. Manual segment arrays are not accepted.

Matrix options

QRCodeMatrixOptions contains only options that affect the encoded matrix:

Option	Type	Default	Constraint
`mode`	`'numeric' \| 'alphanumeric' \| 'octet'`	automatic	Forced mode must accept the entire payload
`eci`	`boolean`	`false`	Only affects symbols containing octet segments
`errorCorrectionLevel`	`'L' \| 'M' \| 'Q' \| 'H'`	`'M'`	Higher redundancy reduces payload capacity
`version`	integer `1`–`40`	automatic	Pinned version must fit the encoded payload
`mask`	integer `0`–`7`	automatic	Pin only when deterministic matrix output is required

Set options individually or together:

1
const builder = qrcode('Grüße ✅').mode('octet').eci(true).errorCorrection('H').version(4).mask(2);
2

3
const equivalent = qrcode('Grüße ✅').config({
4
  mode: 'octet',
5
  eci: true,
6
  errorCorrectionLevel: 'H',
7
  version: 4,
8
  mask: 2,
9
});

ECI and UTF-8

Octet payload bytes are always UTF-8. Enabling eci emits ECI assignment 26 once, immediately before the first octet segment, so scanners receive an explicit UTF-8 declaration. It adds 12 bits. With eci: false, scanners may rely on heuristics for non-ASCII text.

No ECI header is emitted when a symbol contains no octet segment, so numeric- and alphanumeric-only symbols are identical with either setting.

Error correction

The levels L, M, Q, and H add increasing amounts of redundant data. The default is M. Higher levels can tolerate more damaged or obscured modules, but reduce capacity and may select a larger version. For visual overlays, see the reliability guidance in Customize appearance.

Version and mask

When a pinned version cannot contain the payload, generation throws QRCode: Data too large. Removing the override helps only if a larger version can fit the payload. If automatic selection also fails, shorten or change the payload.

Builder methods

Method	Returns	Effect
`.data(value)`	a builder with data	Sets or replaces the input
`.config(options?)`	a configured builder	Merges all supplied matrix options
`.mode(mode?)`	a configured builder	Forces or clears the encoding mode
`.eci(enabled?)`	a configured builder	Enables or clears the UTF-8 ECI declaration
`.errorCorrection(level?)`	a configured builder	Sets or clears the error correction level
`.version(version?)`	a configured builder	Pins or clears the version
`.mask(mask?)`	a configured builder	Pins or clears the mask
`.matrix()`	`QRCodeMatrix`	Generates the matrix; requires data
`.renderer(renderer)`	a builder with a renderer	Stores a renderer for a later call
`.render(renderer?)`	renderer output	Generates the matrix and invokes a supplied or stored renderer

The builder’s types prevent .matrix() or .render() before data is set, and prevent .render() without either a stored or directly supplied renderer.

Matrix output and renderer contract

.matrix() returns a two-dimensional QRCodeMatrix. Each module is 1 for dark or 0 for light. This is the only raw matrix-output contract.

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

3
const matrix: QRCodeMatrix = qrcode('custom output').matrix();

A QRCodeRenderer<TOutput> receives that matrix and returns TOutput:

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

3
const jsonRenderer: QRCodeRenderer<string> = (matrix) =>
4
  JSON.stringify({size: matrix.length, matrix});
5

6
const direct = qrcode('renderer output').render(jsonRenderer);
7
const stored = qrcode('renderer output').renderer(jsonRenderer).render();

Built-in renderers follow the same function contract. Custom renderers own their output geometry, styling, validation, and return type; see Custom renderers.