QR encoder

@opentui/qrcode includes a standalone QR Code Model 2 encoder in addition to QRCodeRenderable. Use the encoder when you need a module matrix, terminal string, SVG, raw bytes, explicit segments, GS1/FNC1, ECI, or structured append.

bun add @opentui/qrcode

Encode text

import { ErrorCorrectionLevel, QRCode } from "@opentui/qrcode"

const qr = QRCode.encodeText("https://opentui.com", ErrorCorrectionLevel.M)

console.log(`version=${qr.version} size=${qr.size} mask=${qr.mask}`)
console.log(qr.toTerminalString({ ansi: true }))

encodeText() chooses the first version in the configured range that fits, optimizes mixed text into numeric, alphanumeric, byte, and optionally Kanji segments, and automatically chooses the lowest-penalty mask unless one is forced.

The requested error-correction level defaults to M. Because boostEcl defaults to true, the resulting qr.errorCorrectionLevel may be upgraded when the same selected version has room for a stronger level.

Encoding options

interface EncodeOptions {
  minVersion?: number
  maxVersion?: number
  mask?: number
  boostEcl?: boolean
  optimize?: boolean
  kanji?: boolean
  byteEncoding?: ByteEncoding
  eciForUtf8?: boolean
  eciAssignment?: number | null
  fnc1First?: boolean
  fnc1Second?: { applicationIndicator: string | number }
  structuredAppend?: { position: number; total: number; parity: number }
}

ByteEncoding is "utf-8" | "iso-8859-1" | "shift-jis". The exported EciAssignment constants are ISO_8859_1: 3, SHIFT_JIS: 20, and UTF_8: 26.

UTF-8 and Shift JIS text byte segments receive their known ECI by default. ISO-8859-1 receives no automatic ECI. Numeric, alphanumeric, and Kanji segments do not need a byte-encoding ECI. Use encodeTextBytes(text, encoding) when the encoded bytes themselves are needed.

Other encoders

All encoder methods default to error-correction level M and EncodeOptions = {} unless shown otherwise.

Raw bytes and explicit ECI

For raw bytes that require an ECI designator, provide the ECI segment explicitly:

import { EciAssignment, ErrorCorrectionLevel, QRCode, QrSegment } from "@opentui/qrcode"

const qr = QRCode.encodeSegments(
  [QrSegment.makeEci(EciAssignment.ISO_8859_1), QrSegment.makeBytes([0x48, 0xe9])],
  ErrorCorrectionLevel.M,
)

QRCode.encodeEciText() and QrSegment.makeEciSegmentsFromEscapedText() recognize a backslash followed by exactly six decimal digits as an ECI switch. A doubled backslash encodes one literal backslash. The segment helper defaults to ISO-8859-1 until a known ECI changes the encoding.

const qr = QRCode.encodeEciText("\\000026Hello, 世界")

The encoder can signal any ECI assignment from 0 through 999999. It only performs text conversion for its known byte encodings; callers must provide already converted bytes for application-defined ECI transformations.

GS1/FNC1

Pass a prebuilt GS1 payload string, or let Gs1Element[] join application identifiers and data. Parentheses are not encoded. Set separatorAfter where a field separator is required before another element:

const qr = QRCode.encodeGs1Text([
  { ai: "10", data: "LOT42", separatorAfter: true },
  { ai: "17", data: "260731" },
])

For FNC1 second position, applicationIndicator accepts an integer from 0 to 99, exactly two decimal digits, or one Latin letter. fnc1First and fnc1Second cannot be used together.

Structured append

const parts = ["PART ONE", "PART TWO"].map((text) => QrSegment.makeSegments(text))
const symbols = QRCode.encodeStructuredAppend(parts)

encodeStructuredAppend() requires 2–16 parts, computes XOR parity from the source segment bytes, and adds the 1-based position and total to each symbol. For manual headers, use QrSegment.makeStructuredAppendHeader(position, total, parity) or QRCode.computeStructuredAppendParity(segments).

Segment API

QrSegment has a private constructor; create segments with its static methods:

Mode predicates isNumeric(), isAlphanumeric(), and isKanji() are also public. segment.getTotalBits(version) returns the encoded segment size for that version, or Infinity when its character count does not fit.

Matrix and metadata

Encoded QRCode instances expose:

QRCode.validateVersionPublic(version) validates the 1–40 range. QRCode.maskCondition(mask, x, y) exposes the mask formulas for callers that inspect encoded matrices.

Terminal output

console.log(
  qr.toTerminalString({
    border: 4,
    ansi: true,
    invert: false,
  }),
)

Each QR module occupies two terminal columns. The returned rows are joined with "\n" and have no trailing newline. A number passed directly to toTerminalString(number) is treated as the border with ANSI and inversion disabled.

SVG output

const svg = qr.toSvgString({
  border: 4,
  moduleSize: 8,
  lightColor: "#ffffff",
  darkColor: "#111827",
})

toSvgString() defaults to border 4, module size 1, light #FFFFFF, and dark #000000. The border must be an integer of at least 4. Pass a finite positive moduleSize: values less than or equal to zero throw, while the current implementation does not reject NaN or Infinity before producing unusable dimensions. Color strings are XML-escaped before insertion.

For a text-to-SVG shortcut:

import { createQrSvg, ErrorCorrectionLevel } from "@opentui/qrcode"

const svg = createQrSvg("https://opentui.com", {
  ecl: ErrorCorrectionLevel.H,
  border: 4,
  moduleSize: 8,
})

createQrSvg() defaults to ECC M, border 4, and module size 8; other encoding options are forwarded to encodeText().

Root exports and limits

The encoder exports from @opentui/qrcode are QRCode, QrSegment, ErrorCorrectionLevel, EciAssignment, encodeTextBytes, createQrSvg, and the types ByteEncoding, EncodeOptions, StructuredAppendInfo, Fnc1SecondPositionInfo, Gs1Element, and TerminalRenderOptions. The same root also exports QRCodeRenderable, QRCodeOptions, and QRCodeFitMode for OpenTUI rendering.

The implementation generates QR Code Model 2 versions 1–40. It does not generate legacy Model 1 or rMQR symbols and does not decode QR codes. Encoding throws when data cannot fit the requested version range and error-correction level. The SVG and terminal helpers enforce a minimum four-module quiet zone, but successful scanning still depends on output scale, contrast, terminal cell geometry, font, display, and camera conditions.