@carrot/qr

Zero-dependency QR code encoder. Handles version selection, encoding mode detection, Reed–Solomon error correction, matrix construction with masking, and a pixel grid for renderers.

Installation

import { create, createGrid } from '@carrot/qr';

Zero dependencies. Works in browser and Node.

Architecture

Encoding Pipeline

text → detectMode → getBestFitVersion → buildBitstream → splitBlocks
     → generateEccBlocks (Reed–Solomon) → interleave → bytesToBits
     → buildMatrix (placement + masking) → QrCode

Mode detection - auto-selects Numeric, Alphanumeric, or Byte based on input characters
Version selection - finds the smallest version (1–40) that fits the data at the chosen ECC level
Bitstream - encodes data with mode indicator, character count, and padding
Block splitting - divides codewords into groups per the spec's block structure tables
Reed–Solomon - generates error correction codewords per block using GF(256) polynomial division
Interleaving - interleaves data and ECC blocks for burst error resilience
Matrix building - places function patterns (finders, timing, alignment, format/version info), then data bits in the zigzag pattern, applies all 8 mask patterns, scores each, and selects the best

Module Types

Every cell in the matrix is typed (ModuleType) so renderers can distinguish data modules from function patterns. This enables styled rendering - e.g. different colours for finders vs data, or skipping function pattern cells for custom finder rendering.

Pixel Grid

createGrid() converts the module matrix into a QrPixelGrid with cardinal neighbour lookup (north/south/east/west, hasDarkNorth/South/East/West). This is the interface renderers use - neighbour awareness enables smooth/rounded rendering styles without re-scanning the matrix.

File Structure

src/
├── index.ts                    # Public API barrel
├── create.ts                   # create(), createFromBytes(), createGrid()
├── types.ts                    # Enums, QrCode, QrModule, QrPixel, QrPixelGrid
├── encoding/
│   ├── mode-detect.ts          # Auto-detect numeric/alphanumeric/byte
│   ├── data-tables.ts          # Version capacity tables, ECC block structure
│   ├── bitstream.ts            # Data bitstream encoding
│   ├── bit-buffer.ts           # Bit-level buffer utilities
│   ├── blocks.ts               # Block splitting + interleaving
│   └── reed-solomon.ts         # GF(256) Reed–Solomon ECC
├── matrix/
│   ├── placement.ts            # Function pattern placement + data zigzag
│   ├── builder.ts              # Full matrix build + mask selection
│   ├── masks.ts                # 8 mask pattern implementations
│   └── format-info.ts          # Format + version info encoding
└── rendering/
    └── pixel-grid.ts           # QrPixelGrid with neighbour lookup

Dependencies

None.

Build

bash

npm run build

Compiles TypeScript to ESM via tsc. Output lands in dist/.

Using @carrot/qr

Zero-dependency QR code encoder with typed pixel output for custom rendering.

Import

import { create, createGrid, ErrorCorrection } from '@carrot/qr';

Common Patterns

1. Encode a URL

const code = create('https://example.com');
// code.version, code.size, code.modules

Default ECC is Low. Use High if you plan to use a center cutout (logo overlay):

const code = create('https://example.com', ErrorCorrection.High);

2. Direct pixel access

for (let y = 0; y < code.size; y++) {
    for (let x = 0; x < code.size; x++) {
        if (code.pixel(x, y)) {
            // dark module at (x, y)
        }
    }
}

3. Pixel grid with neighbours

For renderers that need neighbour awareness (rounded corners, smooth blobs):

const grid = createGrid(code);

for (let y = 0; y < grid.size; y++) {
    for (let x = 0; x < grid.size; x++) {
        const pixel = grid.pixels[y][x];
        if (!pixel.isDark) continue;

        // Neighbour checks for smooth rendering
        const hasTop = grid.hasDarkNorth(x, y);
        const hasRight = grid.hasDarkEast(x, y);

        // Full neighbour pixel (or null at edges)
        const above = grid.north(x, y);
    }
}

4. Encode raw bytes

import { createFromBytes } from '@carrot/qr';

const payload = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
const code = createFromBytes(payload, ErrorCorrection.Medium);

5. Module type inspection

Each module carries its type - useful for styled rendering:

import { ModuleType } from '@carrot/qr';

for (const row of code.modules) {
    for (const mod of row) {
        if (mod.type === ModuleType.Finder) {
            // draw finder pattern differently
        }
    }
}

6. Use with the Vue renderer

import { CarrotQr } from '@carrot/qr-vue';

vue

<CarrotQr url="https://example.com" variant="smooth" :cutout="0.2">
    <img src="/logo.svg" />
</CarrotQr>

Error Correction Levels

Level	Recovery	Use Case
`Low`	~7%	Maximum data capacity
`Medium`	~15%	General purpose
`Quality`	~25%	Moderate damage tolerance
`High`	~30%	Best for logo overlays / center cutouts

Tips

Use High ECC with center cutouts - the cutout destroys modules, so you need the extra error correction capacity.
createGrid is optional - only needed if your renderer uses neighbour awareness. For simple pixel-on/pixel-off rendering, code.pixel(x, y) is sufficient.
Version auto-selects - the encoder picks the smallest QR version (1–40) that fits your data at the chosen ECC level.

Package Contents

@carrot/qr-vue

Import: import { ... } from '@carrot/qr-vue';

Vue Component

CarrotQr - renders a QR code to canvas with reactive prop-driven updates.

Prop	Type	Default	Description
`url`	`string`	required	Text or URL to encode
`w`	`number \| string`	`200`	Width in CSS pixels (retina rendered at 2x)
`ecc`	`'low' \| 'medium' \| 'quality' \| 'high'`	`'high'`	Error correction level
`variant`	`'basic' \| 'dots' \| 'smooth'`	`'smooth'`	Render style
`fg`	`string?`	CSS `--qr-fg` or `'#ffffff'`	Foreground colour
`bg`	`string?`	CSS `--qr-bg` or `'transparent'`	Background colour
`accent`	`string?`	CSS `--qr-accent` or fg	Accent colour (finders + alignment)
`cornerRadius`	`number \| string`	`0.4`	Corner radius (0–0.5)
`dotSize`	`number \| string`	`0.75`	Dot size fraction (dots variant, 0.3–1.0)
`cutout`	`number \| string`	`0`	Centre cutout size (0–0.4, fraction of QR size)
`finderStyle`	`'square' \| 'rounded' \| 'circle'`	`'circle'`	Finder pattern style
`finderColor`	`string?`	accent	Finder pattern colour override

Slot: Default slot content is rendered as an overlay in the centre cutout area.

CSS custom properties: --qr-fg · --qr-bg · --qr-accent (read from the canvas element)

Renderer

renderToCanvas(canvas, code, grid, opts?) - render a QR code onto a canvas element. Returns the canvas.

renderToOffscreen(code, grid, size, opts?) - create and render to a detached canvas.

Render Options

QrRenderOptions:

Field	Type	Default	Description
`variant`	`QrRenderVariant`	`'smooth'`	`'basic'` · `'dots'` · `'smooth'`
`foreground`	`string`	`'#ffffff'`	Dark module colour
`background`	`string`	`'transparent'`	Background colour
`accent`	`string`	foreground	Accent for finders + alignment
`cornerRadius`	`number`	`0.4`	0 = square, 0.5 = full pill
`dotSize`	`number`	`0.75`	Dot size fraction (dots variant)
`quietZone`	`number`	`2`	Quiet zone in modules
`centerCutout`	`CenterCutout?`	-	Centre logo area
`finderStyle`	`string`	`'rounded'`	`'square'` · `'rounded'` · `'circle'`
`finderColor`	`string`	accent	Finder colour override

CenterCutout - { size, background?, cornerRadius?, padding? }

Maths

Logging

QR

Input

Colors

Audio

@carrot/qr

Installation

Architecture

Encoding Pipeline

Module Types

Pixel Grid

File Structure

Dependencies

Build

Using @carrot/qr

Import

Common Patterns

1. Encode a URL

2. Direct pixel access

3. Pixel grid with neighbours

4. Encode raw bytes

5. Module type inspection

6. Use with the Vue renderer

Error Correction Levels

Tips

Package Contents

@carrot/qr-vue

Vue Component

Renderer

Render Options

@carrot/qr ​

Installation ​

Architecture ​

Encoding Pipeline ​

Module Types ​

Pixel Grid ​

File Structure ​

Dependencies ​

Build ​

Using @carrot/qr ​

Import ​

Common Patterns ​

1. Encode a URL ​

2. Direct pixel access ​

3. Pixel grid with neighbours ​

4. Encode raw bytes ​

5. Module type inspection ​

6. Use with the Vue renderer ​

Error Correction Levels ​

Tips ​

Package Contents ​

@carrot/qr-vue ​

Vue Component ​

Renderer ​

Render Options ​

@carrot/qr

Installation

Architecture

Encoding Pipeline

Module Types

Pixel Grid

File Structure

Dependencies

Build

Using @carrot/qr

Import

Common Patterns

1. Encode a URL

2. Direct pixel access

3. Pixel grid with neighbours

4. Encode raw bytes

5. Module type inspection

6. Use with the Vue renderer

Error Correction Levels

Tips

Package Contents

@carrot/qr-vue

Vue Component

Renderer

Render Options