Vize

QR Code

Dependency-free QR Code encoder and headless SVG renderer.
Package @vizejs/ui/qr-code
Maturity stable
Own the source vize lib pull qr-code
Requires —
Aliases qr-code, qr, qrcode, 2d barcode, matrix code
Covers ISO/IEC 18004 QR Code model 2, Project Nayuki QR Code generator, Ark UI QR Code, Mantine QR code examples

Usage

import { QrCode } from "@vizejs/ui/qr-code";

Or copy the source into your project with vize lib pull qr-code (see Source Distribution).

API

QrCode

Source: src/families/media/qr-code/qr-code.vue

Props

Prop Type Default Description
value (required) QrCodeValue required Text (segmented automatically; byte runs are UTF-8), bytes, or explicit segments from the createQrCode*Segment helpers.
errorCorrection QrCodeErrorCorrection "M" Minimum error correction level. Prefer "H" when an overlay covers the center.
boostErrorCorrection boolean false Raise the error correction level while the data still fits the chosen version.
version QrCodeVersion | "auto" "auto" Fixed symbol version, or "auto" for the smallest fitting version.
mask QrCodeMask | "auto" "auto" Fixed data mask, or "auto" for the lowest-penalty mask.
mode QrCodeMode | "auto" "auto" Forced single encoding mode, or "auto" to follow segmentation.
segmentation QrCodeSegmentation "optimal" Automatic segmentation: "optimal" mixes modes for the fewest bits, "single" keeps the most compact single mode.
kanji QrCodeKanjiEncoder undefined Shift_JIS mapping enabling Kanji segments, e.g. qrCodeKanjiEncoder imported from the opt-in Kanji table module.
eci number undefined ECI designator written before the data (26 = UTF-8, 20 = Shift_JIS).
utf8Eci boolean false Declare UTF-8 byte data with ECI 26.
quietZone number 4 Light margin in modules around the symbol. Scanners expect 4.
label string undefined Accessible name. Defaults to the text value; byte values need an explicit label.
decorative boolean false Hide the symbol from assistive technology when adjacent text already conveys it.
foreground string "currentColor" SVG fill for dark modules. Consumer CSS on [part="modules"] can override it.
background string "none" SVG fill for the light background. Consumer CSS on [part="background"] can override it.

Slots

Slot Slot props Description
overlay QrCodeSlotState SVG content drawn above the modules, in module coordinates (for example a centered <image> logo). Only rendered while the value encodes.
fallback QrCodeSlotState Content rendered instead of the symbol when the value cannot be encoded.

Exposed

Member Type Description
state QrCodeState Whether the value encoded successfully.
matrix QrCodeMatrix | null Encoded symbol, or null when encoding failed.
error QrCodeEncodeErrorLike | null Encoding diagnostic, or null when the value encoded successfully.
dimension number Rendered viewBox side length in modules, including the quiet zone.
quietZone number Quiet zone width in modules.
element SVGSVGElement | null Rendered <svg> element, or null while encoding fails.

Behavior

Normative state x input -> outcome table for qr-code.vue and the pure encoder exported from @vizejs/ui/qr-code (encodeQrCode, qrCodeToSvgPath, qrCodeCapacity, isQrCodeModuleDark). Every row is proven by the named test.

The encoder implements ISO/IEC 18004 model 2 symbols without dependencies: optimally mixed numeric, alphanumeric, UTF-8 byte, and (with the opt-in qrCodeKanjiEncoder table from qr-code-kanji.ts) Kanji segments, optional ECI headers, explicit segment arrays, versions 1-40, levels L/M/Q/H with optional boost, Reed-Solomon over GF(256) with block interleaving, finder/timing/alignment/format/version patterns, and all eight masks with the standard penalty score. With segmentation: "single", output is identical to Project Nayuki's reference generator; the default optimal segmentation is the same symbol whenever it settles on one segment, and otherwise never needs a larger version.

ID State Input Outcome Evidence
Q1 byte text, level L encodeQrCode("Hello, world!") produces the reference version 1, mask 2 module grid matches the reference byte-mode symbol for Hello, world! at level L
Q2 numeric / alphanumeric auto mode selects the compact mode and produces the reference grids matches reference numeric and alphanumeric symbols
Q3 multi-block, v7+ long URL at level H interleaves blocks, draws version information, and matches the reference version 9 grid matches a multi-block reference symbol with version information
Q4 spec worked example 01234567 at 1-M emits the standard data codewords, Reed-Solomon codewords, and interleaved stream reproduces the ISO/IEC 18004 worked example codewords for 01234567 at 1-M
Q5 alphanumeric segment AC-42 packs character pairs into 11 bits and a trailing character into 6 bits encodes alphanumeric pairs from the standard AC-42 example
Q6 Reed-Solomon field multiply, generator degree GF(256) arithmetic and generator polynomials match the standard; invalid degrees throw implements GF(256) arithmetic and Reed-Solomon generators
Q7 format information every level x mask emits the 32 masked BCH format strings from table C.1 computes format information for every level and mask
Q8 version information versions 7, 21, 40 emits the standard 18-bit BCH version strings computes version information for versions 7 through 40
Q9 alignment patterns versions 1-40 centers match the standard table, including the irregular version 32 places alignment patterns at the standard centers
Q10 capacity version x level x mode codeword and character capacities match the standard tables matches the standard codeword capacity tables
Q11 auto version data at and over each capacity boundary picks the smallest fitting version and moves up exactly one byte past capacity selects the smallest version at the exact capacity boundary
Q12 invalid input overflow, forced mode, bad options throws QrCodeEncodeError with VIZE_UI_QR_DATA_TOO_LONG, VIZE_UI_QR_INVALID_MODE, or …INVALID_OPTION throws typed diagnostics for data overflow and invalid options
Q13 explicit options fixed version/mask, forced mode, boost honors each option; boost raises the level only while the data still fits honors fixed version, fixed mask, forced mode, and error correction boost
Q14 text encodings Unicode text, bytes, empty string Unicode text equals its UTF-8 bytes; empty values encode a version 1 symbol with mode: null encodes UTF-8 text and empty values
Q15 auto mask encode applies the lowest-penalty mask; output is frozen and deterministic picks the mask with the lowest penalty and returns frozen output
Q16 penalty rules synthetic grids runs, 2x2 blocks, finder-like patterns, and balance follow the standard weights scores the four standard penalty rules
Q17 SVG path module rows merges each horizontal dark run into one rectangle merges horizontal dark runs into one rectangle per run
Q18 SVG path, quiet zone quietZone offsets every coordinate by the quiet zone offsets every coordinate by the quiet zone
Q19 SVG path coverage encoded symbol rasterized path covers exactly the dark modules with no overlap covers exactly the dark modules of an encoded symbol
Q20 SVG path options invalid quiet zone rejects negative, fractional, or oversized quiet zones rejects invalid quiet zones
Q21 ready render renders <svg role="img"> named by label or text, <title>, viewBox with quiet zone, and data hooks renders an accessible SVG symbol with a quiet zone and data hooks
Q22 ready prop change forwards encoder props and re-encodes reactively forwards encoder options and re-encodes when props change
Q23 labelled / decorative render byte values use label; decorative symbols drop role, name, and title and set aria-hidden; fills apply supports explicit labels, byte values, decorative symbols, and colors
Q24 ready + overlay render overlay slot renders inside the SVG with dimension and matrix slot state renders the overlay slot inside the SVG with module coordinates
Q25 error unencodable value or invalid quiet zone renders <span data-state="error" data-error> with the fallback slot, and recovers when props become valid renders the fallback slot with a typed diagnostic when encoding fails
Q26 exposed instance ref access exposes element, matrix, state, error, quiet zone, and dimension exposes the encoded matrix, state, and element
Q27 SSR two isolated requests byte-identical markup, computed purely from props renders byte-identical QR code markup across isolated SSR requests
Q28 SSR + hydration mount over server HTML keeps server nodes and emits no warnings hydrates the QR code without replacing server nodes or warning
Q29 optimal segmentation random text, versions 1/10/27 segment bit length equals an exhaustive search over every split and legal mode optimal segmentation matches an exhaustive search for every version range
Q30 mixed text alphanumeric URL with digits mixes modes to use fewer bits than single mode, re-optimizes per count-width range, reports mixed mixes modes to beat single-mode encoding and re-optimizes per version range
Q31 round trip random text, Kanji, UTF-8 ECI the encoded data stream decodes back to the text; summaries match the emitted segments encodes segments whose data stream decodes back to the original text
Q32 auto version long mixed text the chosen version fits its range's segments and the version below does not chooses the smallest version using the segments of each version range
Q33 Kanji table JIS X 0208, spec examples 点/茗 pack to 0x0D9F/0x1AAA; every JIS X 0208 character round-trips; JIS aliases encode; others do not maps JIS X 0208 characters to Shift_JIS and packs 13-bit Kanji values
Q34 Kanji mode encoder present / absent, forced mode Kanji is used only with an encoder; forced Kanji without one or with unmappable text throws; capacity table uses Kanji mode only with an encoder and validates Kanji input
Q35 ECI segment designators 8/16/24-bit designators, validated range, and header bits in the data stream writes ECI headers with 8, 16, and 24 bit designators
Q36 eci / utf8Eci encode prefixes the header, counts it toward capacity, reports eci, and rejects conflicting options utf8Eci and eci prefix the data and count toward capacity
Q37 explicit segments segment array value encodes the given segments verbatim with frozen helper output; invalid helper input throws encodes explicit segment arrays as given
Q38 component options segmentation, kanji, ECI, segments forwards every encoder option reactively and accepts explicit segments with a label forwards segmentation, Kanji, and ECI options and accepts explicit segments

Colors are SVG presentation attributes (foreground defaults to currentColor, background to none), so consumer CSS on [part="modules"] and [part="background"] always wins. Scanners need a light background and a 4-module quiet zone; use level H when an overlay covers the center.

Released under the MIT License.

Copyright © 2024-2026 ubugeeei