The highest tagged major version is v2.

qrcode

package module

v1.0.0 Latest Latest Go to latest Published: Apr 19, 2026 License: MIT Imports: 16 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/os-gomod/qrcode

Links

Open Source Insights

README ¶

README.md - Comprehensive Documentation

QRcode - Feature-rich QR code generation library for Go

A production-ready, feature-rich QR code generation library for Go with zero external dependencies. Generate QR codes from 30+ payload types, render them in 5 output formats, and customize appearance with advanced module shapes, gradient fills, transparency, and logo overlays.

Overview

qrcode is a comprehensive Go library for generating QR codes in any application. It provides three progressively powerful API levels — quick one-liner functions, a reusable Generator interface, and a fluent Builder — so you can choose the right abstraction for your use case.

The library encodes data through strongly-typed payload structs that validate their own fields before encoding, covering everything from plain text and URLs to WiFi credentials, vCard contacts, calendar events, cryptocurrency payment URIs, social media profiles, Zoom meeting links, iBeacon advertisements, and more. Rendering supports PNG, SVG, PDF, terminal Unicode art, and base64 data URIs. Module appearance is fully customizable: choose square, rounded, circle, or diamond shapes; apply linear gradient fills at any angle; and control transparency for overlay-friendly QR codes. A logo overlay feature lets you brand your codes with a centered image.

The library is built with zero external dependencies — everything is implemented using the Go standard library. Internal utilities include buffer pooling for reduced allocations, singleflight deduplication of in-flight requests, lifecycle management for graceful shutdown, and structured logging.

Installation

go get github.com/os-gomod/qrcode

Quick Start

Generate a PNG QR code from a URL in just three lines:

package main

import (
    "os"

    "github.com/os-gomod/qrcode"
)

func main() {
    data, err := qrcode.Quick("https://github.com/os-gomod/qrcode", 300)
    if err != nil {
        panic(err)
    }
    os.WriteFile("qr.png", data, 0644)
}

The Quick function creates a generator internally, renders the QR code at 300x300 px, and returns the raw PNG bytes. The optional size parameter defaults to 256 px when omitted.

Usage

Basic Generation

The library offers three API levels depending on how much control you need.

Quick Functions

One-shot helpers for the most common payloads. Each creates a short-lived generator, renders to PNG, and returns bytes.

// Plain text
data, err := qrcode.Quick("Hello, World!", 300)

// URL
data, err := qrcode.QuickURL("https://example.com", 300)

// Write directly to a file (format inferred from extension)
err := qrcode.QuickFile("Hello, World!", "output.svg", 300)
err := qrcode.QuickFile("Hello, World!", "output.pdf", 300)

Generator Interface

For repeated use, create a Generator once and reuse it across calls. The generator manages its own resources — call Close when done.

ctx := context.Background()

gen, err := qrcode.New(
    qrcode.WithDefaultSize(300),
    qrcode.WithErrorCorrection(qrcode.LevelH),
    qrcode.WithQuietZone(4),
)
if err != nil {
    panic(err)
}
defer gen.Close(ctx)

p := &payload.TextPayload{Text: "https://example.com"}
qr, err := gen.Generate(ctx, p)
if err != nil {
    panic(err)
}
// qr is an *encoding.QRCode — encode/decode as needed

The Generator interface exposes the following methods:

type Generator interface {
    Generate(ctx context.Context, p payload.Payload) (*encoding.QRCode, error)
    GenerateWithOptions(ctx context.Context, p payload.Payload, opts ...Option) (*encoding.QRCode, error)
    GenerateToWriter(ctx context.Context, p payload.Payload, w io.Writer, format Format) error
    Batch(ctx context.Context, payloads []payload.Payload, opts ...Option) ([]*encoding.QRCode, error)
    Close(ctx context.Context) error
    Closed() bool
    SetOptions(opts ...Option) error
}

Builder Pattern

The Builder provides a fluent, chainable API for constructing a generator. It supports all the same options plus convenience methods for one-off generation.

gen, err := qrcode.NewBuilder().
    Size(400).
    ErrorCorrection(qrcode.LevelH).
    ForegroundColor("#1A56DB").
    BackgroundColor("#F0F9FF").
    QuietZone(4).
    Build()
if err != nil {
    panic(err)
}
defer gen.Close(context.Background())

The builder also has shortcut methods that build a generator, render, and return the result in a single call:

png, err := qrcode.NewBuilder().
    Size(300).
    ForegroundColor("#000000").
    QuickURL("https://example.com")

svg, err := qrcode.NewBuilder().
    Size(300).
    QuickSVG("Hello, World!")

err := qrcode.NewBuilder().
    Size(300).
    QuickFile("https://example.com", "output.svg")

Payload Types

Every payload implements the payload.Payload interface:

type Payload interface {
    Encode() (string, error)
    Type() string
    Validate() error
    Size() int
}

Payloads can be created directly as struct literals or through the validated builder functions in the payload package. The builder functions call Validate() before returning, so you get immediate feedback on malformed input.

Text and URL

p, err := payload.Text("Hello, World!")
p, err := payload.URL("https://example.com")

WiFi

// Standard WiFi network
p, err := payload.WiFi("MyNetwork", "secret123", "WPA2")

// Hidden SSID
p, err := payload.WiFiWithHidden("MyNetwork", "secret123", "WPA2")

vCard Contact

p, err := payload.Contact("John", "Doe",
    payload.WithPhone("+1-555-0123"),
    payload.WithEmail("john@example.com"),
    payload.WithOrganization("Acme Corp"),
    payload.WithTitle("Engineer"),
    payload.WithAddress("123 Main St, Springfield"),
    payload.WithURL("https://example.com"),
    payload.WithNote("QR contact"),
)

MeCard

A lightweight alternative to vCard, commonly used on feature phones:

p := &payload.MeCardPayload{
    Name:    "John Doe",
    Phone:   "+1-555-0123",
    Email:   "john@example.com",
    URL:     "https://example.com",
    Note:    "MeCard contact",
}

Email

p, err := payload.Email("hello@example.com", "Subject Line", "Body text", "cc1@example.com", "cc2@example.com")

SMS

p, err := payload.SMS("+15550123", "Hello from QR code!")

Phone

p, err := payload.Phone("+15550123")

MMS

p, err := payload.MMS("+15550123", "Check this out!")

Geo Location

p, err := payload.Geo(37.421999, -122.084015)

Maps

// Google Maps by coordinates
p, err := payload.GoogleMaps(37.421999, -122.084015)

// Google Maps by search query
p, err := payload.GoogleMapsQuery("Coffee shop near Times Square")

// Apple Maps
p, err := payload.AppleMaps(37.421999, -122.084015)

Calendar Event

start := time.Date(2025, 9, 15, 9, 0, 0, 0, time.UTC)
end := time.Date(2025, 9, 15, 10, 0, 0, 0, time.UTC)

p, err := payload.Event("Team Standup", "Room 101", start, end,
    payload.WithAllDay(),
    payload.WithDescription("Weekly sync meeting"),
)

Event Ticket

p := &payload.EventPayload{
    EventID:    "evt-42",
    EventName:  "Go Conference 2025",
    Venue:      "Convention Center",
    StartTime:  time.Date(2025, 9, 20, 9, 0, 0, 0, time.UTC),
    Category:   "Tech",
    Seat:       "A-12",
    Organizer:  "Go Foundation",
}

p, err := payload.Twitter("golang")
p, err := payload.LinkedIn("https://www.linkedin.com/in/johndoe")
p, err := payload.Instagram("golang")
p, err := payload.Facebook("https://www.facebook.com/golang")
p, err := payload.Telegram("golang")
p, err := payload.SpotifyTrack("3n3Ppam7vgaVa1iaRUc9Lp")
p, err := payload.YouTubeVideo("dQw4w9WgXcQ")

WhatsApp

p, err := payload.WhatsApp("15550123", "Hi there!")

Zoom

p, err := payload.Zoom("123-456-7890", "passcode")

Payment

// PayPal
p, err := payload.Payment("johndoe", "25.00", "USD")

// Crypto (BTC, ETH, LTC)
p := &payload.CryptoPayload{
    Address:    "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    Amount:     "0.001",
    Label:      "Donation",
    Message:    "Thanks!",
    CryptoType: payload.CryptoBTC,
}

iBeacon

p, err := payload.IBeacon("A1B2C3D4-E5F6-7890-ABCD-EF1234567890", 1, 42)

NTP

p := &payload.NTPLocalePayload{
    Host:        "time.google.com",
    Port:        "123",
    Version:     4,
    Description: "Google Public NTP",
}

App Store / Google Play

p, err := payload.AppStore("id1234567890")
p, err := payload.PlayStore("com.example.app")

Swiss QR-Bill (PID)

p := &payload.PIDPayload{
    PIDType:       "QRR",
    CreditorName:  "Acme Corp",
    IBAN:          "CH44 3199 9123 0008 8901 2",
    Reference:     "21 00000 00003 13947 14300 09017",
    Amount:        "100.00",
    Currency:      "CHF",
    DebtorName:    "John Doe",
    RemittanceInfo: "Invoice 2025-001",
}

Rendering Options

The library renders QR codes through the renderer package, which supports multiple output formats and visual styles.

Output Formats

Format	Constant	Description
PNG	`qrcode.FormatPNG`	Raster image with full styling support
SVG	`qrcode.FormatSVG`	Scalable vector graphic
PDF	`qrcode.FormatPDF`	PDF document
Terminal	`qrcode.FormatTerminal`	Unicode block characters for CLI output
Base64	`qrcode.FormatBase64`	Base64-encoded PNG data URI (for HTML `<img>` tags)

// PNG bytes
pngData, err := qrcode.GeneratePNG(ctx, gen, p)

// SVG string
svgStr, err := qrcode.GenerateSVG(ctx, gen, p)

// Terminal (Unicode blocks)
asciiArt, err := qrcode.GenerateASCII(ctx, gen, p)
fmt.Print(asciiArt)

// PDF
var pdfBuf bytes.Buffer
err := gen.GenerateToWriter(ctx, p, &pdfBuf, qrcode.FormatPDF)

// Base64 (embed in HTML)
b64, err := qrcode.GenerateBase64(ctx, gen, p)
fmt.Printf(`<img src="%s" alt="QR Code">`, b64)

// Auto-detect format from file extension
err := qrcode.Save(ctx, gen, p, "output.svg")
err := qrcode.Save(ctx, gen, p, "output.pdf")
err := qrcode.Save(ctx, gen, p, "output.png")

Module Shapes

Customize the visual appearance of individual QR code modules using renderer.ModuleStyle:

Shape	Value	Description
Square	`"square"`	Classic QR code modules
Rounded	`"rounded"`	Rounded rectangles with configurable corner radius
Circle	`"circle"`	Circular dots
Diamond	`"diamond"`	Diamond/rotated square modules

// Circle modules
style := &renderer.ModuleStyle{
    Shape: "circle",
}

Gradient Fill

Apply a linear gradient across the QR code modules:

style := &renderer.ModuleStyle{
    Shape:            "rounded",
    Roundness:        0.5,
    GradientEnabled:  true,
    GradientStart:    "#FF6B35",
    GradientEnd:      "#004E89",
    GradientAngle:    135,
}

Transparency

Control module opacity for overlay-friendly QR codes:

style := &renderer.ModuleStyle{
    Shape:        "circle",
    Transparency: 0.7, // 70% opacity
}

Complete Styled Rendering Example

style := &renderer.ModuleStyle{
    Shape:            "rounded",
    Roundness:        0.4,
    GradientEnabled:  true,
    GradientStart:    "#6366F1",
    GradientEnd:      "#EC4899",
    GradientAngle:    45,
    Transparency:     0.9,
}

Logo Overlay

Embed a logo in the center of the QR code. Higher error correction (LevelH) is recommended to ensure scannability.

gen, err := qrcode.New(
    qrcode.WithDefaultSize(400),
    qrcode.WithErrorCorrection(qrcode.LevelH),
    qrcode.WithLogo("logo.png", 0.25),
    qrcode.WithLogoTint("#1A56DB"),
)
if err != nil {
    panic(err)
}
defer gen.Close(context.Background())

qr, err := gen.Generate(context.Background(), &payload.URLPayload{
    URL: "https://example.com",
})

Builder equivalent:

gen, err := qrcode.NewBuilder().
    Size(400).
    ErrorCorrection(qrcode.LevelH).
    Logo("logo.png", 0.25).
    LogoTint("#1A56DB").
    Build()

Logo options:

Option	Description
`WithLogo(source, sizeRatio)`	Set logo image path and fractional size (0.05-0.40)
`WithLogoOverlay(enabled)`	Enable or disable logo overlay
`WithLogoTint(color)`	Apply a tint color to the logo

Error Correction Levels

Error correction determines how much of the QR code can be damaged while remaining scannable. Higher levels allow more damage but increase the QR code size for the same data.

Level	Recovery	Use Case
`LevelL` (~7%)	Minimal damage	Clean environments, maximum data capacity
`LevelM` (~15%)	Moderate damage	Default — good balance of size and durability
`LevelQ` (~25%)	Significant damage	Decorative QR codes, moderate logos
`LevelH` (~30%)	Extensive damage	Logo overlays, printed materials, harsh environments

// Set at construction time
gen, _ := qrcode.New(qrcode.WithErrorCorrection(qrcode.LevelH))

// Override per call
qr, _ := gen.GenerateWithOptions(ctx, p, qrcode.WithErrorCorrection(qrcode.LevelQ))

Options Reference

Core Options

Option	Type	Description
`WithVersion(v int)`	Config	Set QR code version (1-40)
`WithMinVersion(v int)`	Config	Minimum version for auto-sizing
`WithMaxVersion(v int)`	Config	Maximum version for auto-sizing
`WithErrorCorrection(level)`	Config	Default error correction level
`WithAutoSize(bool)`	Config	Enable automatic version selection
`WithMaskPattern(int)`	Config	Mask pattern (0-7), -1 for auto

Rendering Options

Option	Type	Description
`WithDefaultFormat(f Format)`	Config	Default output format
`WithDefaultSize(int)`	Config	Image size in pixels
`WithQuietZone(int)`	Config	Quiet zone (margin) module count
`WithForegroundColor(string)`	Config	Module color (`"#RRGGBB"`)
`WithBackgroundColor(string)`	Config	Background color (`"#RRGGBB"`)

Logo Options

Option	Type	Description
`WithLogo(source, ratio)`	Config	Logo image path and size ratio
`WithLogoOverlay(bool)`	Config	Enable or disable logo overlay
`WithLogoTint(color)`	Config	Logo tint color

Concurrency Options

Option	Type	Description
`WithWorkerCount(int)`	Config	Batch worker goroutine count
`WithQueueSize(int)`	Config	Internal work queue capacity
`WithConcurrency(int)`	Config	Alias for `WithWorkerCount`

Miscellaneous

Option	Type	Description
`WithPrefix(string)`	Config	URI prefix for encoded data

Batch Generation

Generate multiple QR codes concurrently using the Batch method:

payloads := []payload.Payload{
    &payload.URLPayload{URL: "https://example.com/1"},
    &payload.URLPayload{URL: "https://example.com/2"},
    &payload.URLPayload{URL: "https://example.com/3"},
}

gen, _ := qrcode.New(
    qrcode.WithWorkerCount(4),
    qrcode.WithQueueSize(16),
)
defer gen.Close(context.Background())

results, err := gen.Batch(context.Background(), payloads)

Go Doc Reference

Types

type Config

type Config struct {
    DefaultVersion  int
    DefaultECLevel  string
    MinVersion      int
    MaxVersion      int
    AutoSize        bool
    WorkerCount     int
    QueueSize       int
    DefaultFormat   string
    DefaultSize     int
    QuietZone       int
    ForegroundColor string
    BackgroundColor string
    MaskPattern     int
    LogoSource      string
    LogoSizeRatio   float64
    LogoOverlay     bool
    LogoTint        string
    Prefix          string
    SlowOperation   time.Duration
}

Config holds all configuration parameters for the QR code generator. It is created internally via defaultConfig() and modified through Option functions. Use New() or NewBuilder() to construct a generator — do not create Config directly.

Methods:

func (c *Config) Clone() *Config — Returns a shallow copy of the configuration.
func (c *Config) Merge(other *Config) — Merges non-zero fields from other into c.
func (c *Config) Validate() error — Checks that all configuration fields are within valid ranges.

type ErrorCorrectionLevel

type ErrorCorrectionLevel int

Constants: LevelL, LevelM, LevelQ, LevelH.

Method: func (l ErrorCorrectionLevel) String() string — Returns "L", "M", "Q", or "H".

type Format

type Format int

Constants: FormatPNG, FormatSVG, FormatTerminal, FormatPDF, FormatBase64.

Method: func (f Format) String() string — Returns "png", "svg", "terminal", "pdf", or "base64".

type Generator

type Generator interface {
    Generate(ctx context.Context, p payload.Payload) (*encoding.QRCode, error)
    GenerateWithOptions(ctx context.Context, p payload.Payload, opts ...Option) (*encoding.QRCode, error)
    GenerateToWriter(ctx context.Context, p payload.Payload, w io.Writer, format Format) error
    Batch(ctx context.Context, payloads []payload.Payload, opts ...Option) ([]*encoding.QRCode, error)
    Close(ctx context.Context) error
    Closed() bool
    SetOptions(opts ...Option) error
}

The primary interface for creating QR codes. Use New() or NewBuilder().Build() to obtain an implementation. Call Close() when the generator is no longer needed to release resources.

type Option

type Option func(*Config)

A functional option that modifies a Config at construction time. Options are passed to New(), MustNew(), or NewBuilder().Options().

type Builder

type Builder struct { /* unexported */ }

A fluent API for constructing a Generator with chained configuration.

Key methods:

func NewBuilder() *Builder
func (b *Builder) Size(int) *Builder
func (b *Builder) Margin(int) *Builder
func (b *Builder) ErrorCorrection(ErrorCorrectionLevel) *Builder
func (b *Builder) Version(int) *Builder
func (b *Builder) MinVersion(int) *Builder
func (b *Builder) MaxVersion(int) *Builder
func (b *Builder) MaskPattern(int) *Builder
func (b *Builder) Format(Format) *Builder
func (b *Builder) ForegroundColor(string) *Builder
func (b *Builder) BackgroundColor(string) *Builder
func (b *Builder) Logo(string, float64) *Builder
func (b *Builder) LogoOverlay(bool) *Builder
func (b *Builder) LogoTint(string) *Builder
func (b *Builder) WorkerCount(int) *Builder
func (b *Builder) QueueSize(int) *Builder
func (b *Builder) Prefix(string) *Builder
func (b *Builder) AutoSize(bool) *Builder
func (b *Builder) Options(...Option) *Builder
func (b *Builder) Build() (Generator, error)
func (b *Builder) MustBuild() Generator
func (b *Builder) Clone() *Builder
func (b *Builder) Quick(string, ...int) ([]byte, error)
func (b *Builder) QuickSVG(string, ...int) (string, error)
func (b *Builder) QuickFile(string, string, ...int) error
func (b *Builder) QuickURL(string, ...int) ([]byte, error)
func (b *Builder) QuickWiFi(string, string, string, ...int) ([]byte, error)
func (b *Builder) QuickContact(string, string, string, string, ...int) ([]byte, error)
func (b *Builder) QuickSMS(string, string, ...int) ([]byte, error)
func (b *Builder) QuickEmail(string, string, string, ...int) ([]byte, error)
func (b *Builder) QuickGeo(float64, float64, ...int) ([]byte, error)
func (b *Builder) QuickEvent(string, string, time.Time, time.Time, ...int) ([]byte, error)
func (b *Builder) BuildAndGeneratePNG(context.Context, payload.Payload) ([]byte, error)
func (b *Builder) BuildAndGenerateSVG(context.Context, payload.Payload) (string, error)
func (b *Builder) BuildAndSave(context.Context, payload.Payload, string) error

Package-level Functions

func New(opts ...Option) (Generator, error) — Creates a new Generator with the given options.
func MustNew(opts ...Option) Generator — Like New but panics on error.
func Quick(data string, size ...int) ([]byte, error) — Generates a PNG QR code from text.
func QuickSVG(data string, size ...int) (string, error) — Generates an SVG QR code from text.
func QuickFile(data, path string, size ...int) error — Generates a QR code and writes to file.
func QuickURL(url string, size ...int) ([]byte, error) — Generates a PNG QR code from a URL.
func QuickWiFi(ssid, password, encryption string, size ...int) ([]byte, error) — Generates a WiFi QR code.
func QuickContact(firstName, lastName, phone, email string, size ...int) ([]byte, error) — Generates a vCard QR code.
func QuickSMS(phone, message string, size ...int) ([]byte, error) — Generates an SMS QR code.
func QuickEmail(to, subject, body string, size ...int) ([]byte, error) — Generates an email QR code.
func QuickGeo(lat, lng float64, size ...int) ([]byte, error) — Generates a geo location QR code.
func QuickEvent(title, location string, start, end time.Time, size ...int) ([]byte, error) — Generates a calendar event QR code.
func QuickPayment(username, amount string, size ...int) ([]byte, error) — Generates a PayPal payment QR code.
func GeneratePNG(ctx context.Context, gen Generator, p payload.Payload) ([]byte, error) — Renders to PNG bytes.
func GenerateSVG(ctx context.Context, gen Generator, p payload.Payload) (string, error) — Renders to SVG string.
func GenerateASCII(ctx context.Context, gen Generator, p payload.Payload) (string, error) — Renders to terminal Unicode blocks.
func GenerateBase64(ctx context.Context, gen Generator, p payload.Payload) (string, error) — Renders to base64 data URI.
func SavePNG(ctx context.Context, gen Generator, p payload.Payload, path string) error — Saves as PNG file.
func SaveSVG(ctx context.Context, gen Generator, p payload.Payload, path string) error — Saves as SVG file.
func Save(ctx context.Context, gen Generator, p payload.Payload, path string) error — Saves with format inferred from extension.
func ContextWithQR(ctx context.Context, gen Generator) context.Context — Stores a Generator in context.
func QRFromContext(ctx context.Context) (Generator, bool) — Retrieves a Generator from context.

Sub-packages

Package	Description
`encoding`	QR encoding engine — Galois fields, Reed-Solomon error correction, masking, matrix construction, version info tables
`payload`	30+ typed payload structs with `Encode()`, `Validate()`, `Type()`, and `Size()` methods. Each payload validates its own fields. Builder functions (e.g., `payload.Text()`, `payload.URL()`) return validated payloads.
`renderer`	Output renderers for PNG, SVG, PDF, terminal, and base64. Supports module styling (shape, gradient, transparency) via `ModuleStyle`.
`logo`	Logo overlay processing — load images, resize, tint, and composite onto QR codes.
`batch`	Concurrent batch processing with configurable worker pool and work queue.
`errors`	Structured error types with error codes for programmatic handling.
`testing`	Contract tests (`GeneratorContractTest`) and assertion utilities for testing Generator implementations.
`internal/hash`	Fast non-cryptographic payload hashing for singleflight deduplication.
`internal/lifecycle`	Component lifecycle management (open/close state tracking).
`internal/pool`	Sync.Pool-based buffer pool for reducing allocations during encoding.
`internal/singleflight`	Deduplication of in-flight identical requests.

License

This project is licensed under the MIT License.

Maintained by os-gomod | Report Bug | Request Feature

Documentation ¶

Overview ¶

Package qrcode provides a high-performance QR code generation library in pure Go with zero external dependencies. It supports encoding over 30 payload types including URLs, WiFi credentials, vCard contacts, calendar events, social media links, payments, and geographic locations. QR codes can be rendered to PNG, SVG, PDF, terminal Unicode blocks, or base64-encoded data URIs, with support for custom module shapes, gradient fills, transparency, and centered logo overlays.

The library exposes two primary usage patterns. The first is a functional-options Generator interface for long-lived, concurrent use:

     gen, err := qrcode.New(
         qrcode.WithErrorCorrection(qrcode.LevelH),
         qrcode.WithDefaultSize(400),
         qrcode.WithQuietZone(4),
     )
     if err != nil {
         log.Fatal(err)
     }
     defer gen.Close(ctx)

	payload := payload.URL("https://example.com")
	qr, err := gen.Generate(ctx, payload)

The second is a fluent Builder API that chains configuration and provides one-shot convenience methods:

png, err := qrcode.NewBuilder().
    ErrorCorrection(qrcode.LevelQ).
    ForegroundColor("#1a1a2e").
    BackgroundColor("#e0e0e0").
    Quick("https://example.com", 512)

For fire-and-forget use cases, package-level Quick* functions create and discard a generator internally:

png, err := qrcode.Quick("Hello, world!")
svg, err := qrcode.QuickSVG("https://example.com")
err := qrcode.QuickFile("Hello, world!", "output.png")

Batch generation is available through both the Generator.Batch method and the dedicated batch.Processor type, which supports concurrency control, file output, and statistics collection.

Index ¶

func ContextWithQR(ctx context.Context, gen Generator) context.Context
func GenerateASCII(ctx context.Context, gen Generator, p payload.Payload) (string, error)
func GenerateBase64(ctx context.Context, gen Generator, p payload.Payload) (string, error)
func GeneratePNG(ctx context.Context, gen Generator, p payload.Payload) ([]byte, error)
func GenerateSVG(ctx context.Context, gen Generator, p payload.Payload) (string, error)
func Quick(data string, size ...int) ([]byte, error)
func QuickContact(firstName, lastName, phone, email string, size ...int) ([]byte, error)
func QuickEmail(to, subject, body string, size ...int) ([]byte, error)
func QuickEvent(title, location string, start, end time.Time, size ...int) ([]byte, error)
func QuickFile(data, path string, size ...int) error
func QuickGeo(lat, lng float64, size ...int) ([]byte, error)
func QuickPayment(username, amount string, size ...int) ([]byte, error)
func QuickSMS(phone, message string, size ...int) ([]byte, error)
func QuickSVG(data string, size ...int) (string, error)
func QuickURL(url string, size ...int) ([]byte, error)
func QuickWiFi(ssid, password, encryption string, size ...int) ([]byte, error)
func Save(ctx context.Context, gen Generator, p payload.Payload, path string) error
func SavePNG(ctx context.Context, gen Generator, p payload.Payload, path string) error
func SaveSVG(ctx context.Context, gen Generator, p payload.Payload, path string) error
type Builder
- func NewBuilder() *Builder
- func (b *Builder) AutoSize(auto bool) *Builder
- func (b *Builder) BackgroundColor(color string) *Builder
- func (b *Builder) Build() (Generator, error)
- func (b *Builder) BuildAndGeneratePNG(ctx context.Context, p payload.Payload) ([]byte, error)
- func (b *Builder) BuildAndGenerateSVG(ctx context.Context, p payload.Payload) (string, error)
- func (b *Builder) BuildAndSave(ctx context.Context, p payload.Payload, path string) error
- func (b *Builder) Clone() *Builder
- func (b *Builder) ErrorCorrection(level ErrorCorrectionLevel) *Builder
- func (b *Builder) ForegroundColor(color string) *Builder
- func (b *Builder) Format(f Format) *Builder
- func (b *Builder) Logo(source string, sizeRatio float64) *Builder
- func (b *Builder) LogoOverlay(enabled bool) *Builder
- func (b *Builder) LogoTint(color string) *Builder
- func (b *Builder) Margin(margin int) *Builder
- func (b *Builder) MaskPattern(pattern int) *Builder
- func (b *Builder) MaxVersion(v int) *Builder
- func (b *Builder) MinVersion(v int) *Builder
- func (b *Builder) MustBuild() Generator
- func (b *Builder) Options(opts ...Option) *Builder
- func (b *Builder) Prefix(prefix string) *Builder
- func (b *Builder) QueueSize(n int) *Builder
- func (b *Builder) Quick(data string, size ...int) ([]byte, error)
- func (b *Builder) QuickContact(firstName, lastName, phone, email string, size ...int) ([]byte, error)
- func (b *Builder) QuickEmail(to, subject, body string, size ...int) ([]byte, error)
- func (b *Builder) QuickEvent(title, location string, start, end time.Time, size ...int) ([]byte, error)
- func (b *Builder) QuickFile(data, path string, size ...int) error
- func (b *Builder) QuickGeo(lat, lng float64, size ...int) ([]byte, error)
- func (b *Builder) QuickSMS(phone, message string, size ...int) ([]byte, error)
- func (b *Builder) QuickSVG(data string, size ...int) (string, error)
- func (b *Builder) QuickURL(url string, size ...int) ([]byte, error)
- func (b *Builder) QuickWiFi(ssid, password, encryption string, size ...int) ([]byte, error)
- func (b *Builder) Size(size int) *Builder
- func (b *Builder) Version(v int) *Builder
- func (b *Builder) WorkerCount(n int) *Builder
type Config
- func (c *Config) Clone() *Config
- func (c *Config) Merge(other *Config)
- func (c *Config) Validate() error
type ErrorCorrectionLevel
- func (l ErrorCorrectionLevel) String() string
type Format
- func (f Format) String() string
type Generator
- func MustNew(opts ...Option) Generator
- func New(opts ...Option) (Generator, error)
- func QRFromContext(ctx context.Context) (Generator, bool)
type Option
- func WithAutoSize(auto bool) Option
- func WithBackgroundColor(color string) Option
- func WithConcurrency(n int) Option
- func WithDefaultFormat(f Format) Option
- func WithDefaultSize(size int) Option
- func WithErrorCorrection(level ErrorCorrectionLevel) Option
- func WithForegroundColor(color string) Option
- func WithLogo(logoSource string, sizeRatio float64) Option
- func WithLogoOverlay(enabled bool) Option
- func WithLogoTint(color string) Option
- func WithMaskPattern(pattern int) Option
- func WithMaxVersion(v int) Option
- func WithMinVersion(v int) Option
- func WithPrefix(prefix string) Option
- func WithQueueSize(n int) Option
- func WithQuietZone(zone int) Option
- func WithSlowOperation(d time.Duration) Option
- func WithVersion(v int) Option
- func WithWorkerCount(n int) Option

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func ContextWithQR ¶

func ContextWithQR(ctx context.Context, gen Generator) context.Context

ContextWithQR stores a Generator in the given context using an unexported context key. The stored Generator can later be retrieved with QRFromContext. This is useful in HTTP middleware or request-scoped dependency injection.

func GenerateASCII ¶

func GenerateASCII(ctx context.Context, gen Generator, p payload.Payload) (string, error)

GenerateASCII renders a QR code from the payload as Unicode block characters.

func GenerateBase64 ¶

func GenerateBase64(ctx context.Context, gen Generator, p payload.Payload) (string, error)

GenerateBase64 renders a QR code from the payload as a base64-encoded PNG data URI.

func GeneratePNG ¶

func GeneratePNG(ctx context.Context, gen Generator, p payload.Payload) ([]byte, error)

GeneratePNG renders a QR code from the payload as PNG bytes.

func GenerateSVG ¶

func GenerateSVG(ctx context.Context, gen Generator, p payload.Payload) (string, error)

GenerateSVG renders a QR code from the payload as an SVG string.

func Quick ¶

func Quick(data string, size ...int) ([]byte, error)

Quick generates a PNG QR code from the given text data with an optional image size.

func QuickContact ¶

func QuickContact(firstName, lastName, phone, email string, size ...int) ([]byte, error)

QuickContact generates a PNG QR code encoding a vCard contact.

func QuickEmail ¶

func QuickEmail(to, subject, body string, size ...int) ([]byte, error)

QuickEmail generates a PNG QR code encoding an email message.

func QuickEvent ¶

func QuickEvent(title, location string, start, end time.Time, size ...int) ([]byte, error)

QuickEvent generates a PNG QR code encoding a calendar event.

func QuickFile ¶

func QuickFile(data, path string, size ...int) error

QuickFile generates a QR code from the given text data and writes it to path. The output format is inferred from the file extension (.png, .svg, or .pdf).

func QuickGeo ¶

func QuickGeo(lat, lng float64, size ...int) ([]byte, error)

QuickGeo generates a PNG QR code encoding a geographic location.

func QuickPayment ¶

func QuickPayment(username, amount string, size ...int) ([]byte, error)

QuickPayment generates a PNG QR code encoding a PayPal payment link.

func QuickSMS ¶

func QuickSMS(phone, message string, size ...int) ([]byte, error)

QuickSMS generates a PNG QR code encoding an SMS message.

func QuickSVG ¶

func QuickSVG(data string, size ...int) (string, error)

QuickSVG generates an SVG QR code from the given text data with an optional image size.

func QuickURL ¶

func QuickURL(url string, size ...int) ([]byte, error)

QuickURL generates a PNG QR code encoding the given URL.

func QuickWiFi ¶

func QuickWiFi(ssid, password, encryption string, size ...int) ([]byte, error)

QuickWiFi generates a PNG QR code encoding a WiFi network configuration.

func Save ¶

func Save(ctx context.Context, gen Generator, p payload.Payload, path string) error

Save renders a QR code from the payload and writes it to the given file path. The output format is inferred from the file extension (.png, .svg, or .pdf).

func SavePNG ¶

func SavePNG(ctx context.Context, gen Generator, p payload.Payload, path string) error

SavePNG renders a QR code from the payload and writes the PNG to the given file path.

func SaveSVG ¶

func SaveSVG(ctx context.Context, gen Generator, p payload.Payload, path string) error

SaveSVG renders a QR code from the payload and writes the SVG to the given file path.

Types ¶

type Builder ¶

type Builder struct {
	// contains filtered or unexported fields
}

Builder provides a fluent API for constructing a Generator with chained configuration. Each setter method returns the Builder itself, allowing calls to be chained. The accumulated options are applied when Build or MustBuild is called.

Builder also provides one-shot convenience methods (Quick, QuickURL, QuickWiFi, etc.) that build a generator, render a single QR code, and immediately close the generator.

png, err := qrcode.NewBuilder().
    ErrorCorrection(qrcode.LevelQ).
    ForegroundColor("#1a1a2e").
    BackgroundColor("#e0e0e0").
    Size(512).
    Quick("https://example.com")

For repeated use, call Build once and reuse the Generator:

gen, err := qrcode.NewBuilder().
    ErrorCorrection(qrcode.LevelH).
    QuietZone(4).
    Build()

func NewBuilder ¶

func NewBuilder() *Builder

NewBuilder creates a new Builder with default settings.

func (*Builder) AutoSize ¶

func (b *Builder) AutoSize(auto bool) *Builder

AutoSize enables or disables automatic version selection.

func (*Builder) BackgroundColor ¶

func (b *Builder) BackgroundColor(color string) *Builder

BackgroundColor sets the background color.

func (*Builder) Build ¶

func (b *Builder) Build() (Generator, error)

Build creates a Generator from the accumulated configuration. Returns an error if the combined options produce an invalid configuration.

func (*Builder) BuildAndGeneratePNG ¶

func (b *Builder) BuildAndGeneratePNG(ctx context.Context, p payload.Payload) ([]byte, error)

BuildAndGeneratePNG builds a generator and produces a PNG byte slice from the payload. The generator is closed after rendering. For repeated use, call Build once and use Generator.GenerateToWriter directly.

func (*Builder) BuildAndGenerateSVG ¶

func (b *Builder) BuildAndGenerateSVG(ctx context.Context, p payload.Payload) (string, error)

BuildAndGenerateSVG builds a generator and produces an SVG string from the payload. The generator is closed after rendering.

func (*Builder) BuildAndSave ¶

func (b *Builder) BuildAndSave(ctx context.Context, p payload.Payload, path string) error

BuildAndSave builds a generator and saves the rendered QR code to a file. The format is inferred from the file extension (.png, .svg, or .pdf). The generator is closed after saving.

func (*Builder) Clone ¶

func (b *Builder) Clone() *Builder

Clone returns a shallow copy of the builder with the same options. The returned Builder can be modified independently. Used internally by convenience methods to avoid mutating the caller's Builder.

func (*Builder) ErrorCorrection ¶

func (b *Builder) ErrorCorrection(level ErrorCorrectionLevel) *Builder

ErrorCorrection sets the default error correction level.

func (*Builder) ForegroundColor ¶

func (b *Builder) ForegroundColor(color string) *Builder

ForegroundColor sets the foreground (module) color.

func (*Builder) Format ¶

func (b *Builder) Format(f Format) *Builder

Format sets the default output format.

func (*Builder) Logo ¶

func (b *Builder) Logo(source string, sizeRatio float64) *Builder

Logo configures a centered logo overlay with the given image source and size ratio.

func (*Builder) LogoOverlay ¶

func (b *Builder) LogoOverlay(enabled bool) *Builder

LogoOverlay enables or disables the logo overlay.

func (*Builder) LogoTint ¶

func (b *Builder) LogoTint(color string) *Builder

LogoTint applies a tint color to the overlaid logo.

func (*Builder) Margin ¶

func (b *Builder) Margin(margin int) *Builder

Margin sets the quiet-zone (margin) module count.

func (*Builder) MaskPattern ¶

func (b *Builder) MaskPattern(pattern int) *Builder

MaskPattern sets the mask pattern (0–7).

func (*Builder) MaxVersion ¶

func (b *Builder) MaxVersion(v int) *Builder

MaxVersion sets the maximum QR code version.

func (*Builder) MinVersion ¶

func (b *Builder) MinVersion(v int) *Builder

MinVersion sets the minimum QR code version.

func (*Builder) MustBuild ¶

func (b *Builder) MustBuild() Generator

MustBuild is like Build but panics on error. Useful in short-lived programs where configuration errors should halt immediately.

gen := qrcode.NewBuilder().Size(512).MustBuild()

func (*Builder) Options ¶

func (b *Builder) Options(opts ...Option) *Builder

Options appends arbitrary Option values to the builder.

func (*Builder) Prefix ¶

func (b *Builder) Prefix(prefix string) *Builder

Prefix sets a URI prefix prepended to encoded data.

func (*Builder) QueueSize ¶

func (b *Builder) QueueSize(n int) *Builder

QueueSize sets the internal work queue capacity.

func (*Builder) Quick ¶

func (b *Builder) Quick(data string, size ...int) ([]byte, error)

Quick generates a PNG QR code from the given text data. The optional size argument specifies the image width/height in pixels; defaults to 256.

func (*Builder) QuickContact ¶

func (b *Builder) QuickContact(firstName, lastName, phone, email string, size ...int) ([]byte, error)

QuickContact generates a PNG QR code encoding a vCard contact with the given name, phone, and email. Additional vCard fields can be set by using the payload.Contact builder and Builder.BuildAndGeneratePNG.

func (*Builder) QuickEmail ¶

func (b *Builder) QuickEmail(to, subject, body string, size ...int) ([]byte, error)

QuickEmail generates a PNG QR code encoding an email message.

func (*Builder) QuickEvent ¶

func (b *Builder) QuickEvent(title, location string, start, end time.Time, size ...int) ([]byte, error)

QuickEvent generates a PNG QR code encoding a calendar event (iCalendar VEVENT).

func (*Builder) QuickFile ¶

func (b *Builder) QuickFile(data, path string, size ...int) error

QuickFile generates a QR code from the given text data and writes it to the specified file path. The output format is inferred from the file extension (.png, .svg, or .pdf).

func (*Builder) QuickGeo ¶

func (b *Builder) QuickGeo(lat, lng float64, size ...int) ([]byte, error)

QuickGeo generates a PNG QR code encoding a geographic location (geo: URI).

func (*Builder) QuickSMS ¶

func (b *Builder) QuickSMS(phone, message string, size ...int) ([]byte, error)

QuickSMS generates a PNG QR code encoding an SMS message.

func (*Builder) QuickSVG ¶

func (b *Builder) QuickSVG(data string, size ...int) (string, error)

QuickSVG generates an SVG QR code from the given text data. The optional size argument specifies the image width/height in pixels; defaults to 256.

func (*Builder) QuickURL ¶

func (b *Builder) QuickURL(url string, size ...int) ([]byte, error)

QuickURL generates a PNG QR code encoding the given URL.

func (*Builder) QuickWiFi ¶

func (b *Builder) QuickWiFi(ssid, password, encryption string, size ...int) ([]byte, error)

QuickWiFi generates a PNG QR code encoding a WiFi network configuration. The encryption parameter should be one of the payload.Encryption* constants.

func (*Builder) Size ¶

func (b *Builder) Size(size int) *Builder

Size sets the default image size in pixels.

func (*Builder) Version ¶

func (b *Builder) Version(v int) *Builder

Version sets the QR code version (1–40).

func (*Builder) WorkerCount ¶

func (b *Builder) WorkerCount(n int) *Builder

WorkerCount sets the number of concurrent batch workers.

type Config ¶

type Config struct {
	DefaultVersion  int           `json:"default_version"`  // QR version (1–40); 0 means auto-select
	DefaultECLevel  string        `json:"default_ec_level"` // Error correction: "L", "M", "Q", "H"
	MinVersion      int           `json:"min_version"`      // Minimum version for auto-selection (1–40)
	MaxVersion      int           `json:"max_version"`      // Maximum version for auto-selection (1–40)
	AutoSize        bool          `json:"auto_size"`        // Enable automatic version sizing by data length
	WorkerCount     int           `json:"worker_count"`     // Concurrent goroutines for batch operations (1–64)
	QueueSize       int           `json:"queue_size"`       // Internal work queue capacity (>=1)
	DefaultFormat   string        `json:"default_format"`   // Default render format: "png", "svg", "terminal", "pdf"
	DefaultSize     int           `json:"default_size"`     // Default image width/height in pixels (100–4000)
	QuietZone       int           `json:"quiet_zone"`       // Quiet-zone margin modules around the QR code (0–20)
	ForegroundColor string        `json:"foreground_color"` // Hex color for dark modules (e.g. "#000000")
	BackgroundColor string        `json:"background_color"` // Hex color for light modules (e.g. "#FFFFFF")
	MaskPattern     int           `json:"mask_pattern"`     // Data mask pattern (0–7, or -1 for auto)
	LogoSource      string        `json:"logo_source"`      // File path or URL of the overlay logo image
	LogoSizeRatio   float64       `json:"logo_size_ratio"`  // Fraction of QR image occupied by logo (0.05–0.4)
	LogoOverlay     bool          `json:"logo_overlay"`     // Whether to render the logo overlay
	LogoTint        string        `json:"logo_tint"`        // Hex color to tint the logo image
	Prefix          string        `json:"prefix"`           // URI prefix prepended to encoded data
	SlowOperation   time.Duration `json:"slow_operation"`   // Threshold for logging slow generations
}

Config holds all configuration parameters for the QR code generator. Config is typically constructed implicitly through functional Option values passed to New or NewBuilder, but can also be manipulated directly for advanced use cases such as merging presets.

The zero-value Config is not valid; use defaultConfig (via New) to obtain a Config with sensible defaults, then apply Option overrides.

cfg := qrcode.defaultConfig() // internal; use qrcode.New() instead
qrcode.WithErrorCorrection(qrcode.LevelH)(cfg)

func (*Config) Clone ¶

func (c *Config) Clone() *Config

Clone returns a shallow copy of the configuration. The returned Config can be modified independently without affecting the original. This is used internally to snapshot the configuration under a read lock before applying per-call options.

func (*Config) Merge ¶

func (c *Config) Merge(other *Config)

Merge overlays non-zero fields from other into c. Fields that are their zero value in other are left unchanged in c. This is useful for applying a partial configuration preset on top of a base configuration.

base := defaultConfig()
preset := &Config{DefaultSize: 512, ForegroundColor: "#1a1a2e"}
base.Merge(preset)

func (*Config) Validate ¶

func (c *Config) Validate() error

Validate checks that all configuration fields are within valid ranges and returns an error describing the first violation found. Checked constraints include: MinVersion <= MaxVersion, DefaultVersion within range, WorkerCount (1–64), QueueSize (>=1), DefaultSize (100–4000), QuietZone (0–20), LogoSource required when LogoOverlay is true, LogoSizeRatio (0.05–0.4), and MaskPattern (-1–7).

type ErrorCorrectionLevel ¶

type ErrorCorrectionLevel int

ErrorCorrectionLevel represents the Reed–Solomon error correction level for a QR code. Higher levels provide greater damage tolerance but reduce the available data capacity. The four standard levels are L (7%), M (15%), Q (25%), and H (30%).

LevelH is recommended when a logo overlay is used, as the additional redundancy helps scanners recover the original data despite the obstructed center modules.

const (
	// LevelL recovers approximately 7% of codewords.
	// Suitable for clean environments where the QR code will not be damaged or obscured.
	LevelL ErrorCorrectionLevel = iota
	// LevelM recovers approximately 15% of codewords.
	// The default level and a good balance between capacity and resilience.
	LevelM
	// LevelQ recovers approximately 25% of codewords.
	// Recommended for QR codes that may be partially covered or printed on rough surfaces.
	LevelQ
	// LevelH recovers approximately 30% of codewords.
	// Recommended when using a logo overlay, as the highest redundancy compensates
	// for the obstructed center region.
	LevelH
)

func (ErrorCorrectionLevel) String ¶

func (l ErrorCorrectionLevel) String() string

String returns the human-readable label for the error correction level. Returns "L", "M", "Q", or "H" for valid levels; defaults to "M".

type Format ¶

type Format int

Format enumerates the supported output formats for rendering QR codes.

Each format maps to a dedicated renderer in the renderer sub-package. The Format value is passed to Generator.GenerateToWriter to select the output encoding.

FormatPNG      // raster PNG image, best for web and print
FormatSVG      // vector SVG, best for scalable or styled output
FormatTerminal // Unicode block characters for CLI display
FormatPDF      // standalone PDF document
FormatBase64   // base64-encoded PNG data URI for HTML embedding

const (
	// FormatPNG renders the QR code as a PNG image.
	// Uses the standard Go image/png encoder. Supports module-style customization
	// including rounded, circle, and diamond shapes, gradient fills, and transparency.
	FormatPNG Format = iota
	// FormatSVG renders the QR code as a scalable vector graphic.
	// Produces a self-contained SVG document with no external dependencies.
	FormatSVG
	// FormatTerminal renders the QR code as Unicode block characters for terminal output.
	// Uses half-block characters (\u2580, \u2584, \u2588) to achieve near-square
	// module rendering. Supports 24-bit ANSI color codes when a foreground color is set.
	FormatTerminal
	// FormatPDF renders the QR code as a PDF document.
	// Generates a minimal PDF 1.4 file with the QR code centered on the page.
	FormatPDF
	// FormatBase64 renders the QR code as a base64-encoded PNG data URI.
	// Output is a "data:image/png;base64,..." string suitable for embedding in HTML
	// <img> tags or CSS backgrounds.
	FormatBase64
)

func (Format) String ¶

func (f Format) String() string

String returns the file-extension style label for the format. Returns "png", "svg", "terminal", "pdf", or "base64" for known formats; returns "unknown" for undefined values.

type Generator ¶

type Generator interface {
	// Generate produces a QR code from the given payload using default options.
	Generate(ctx context.Context, p payload.Payload) (*encoding.QRCode, error)
	// GenerateWithOptions produces a QR code with per-call option overrides.
	GenerateWithOptions(ctx context.Context, p payload.Payload, opts ...Option) (*encoding.QRCode, error)
	// GenerateToWriter renders a QR code in the specified format and writes it to w.
	GenerateToWriter(ctx context.Context, p payload.Payload, w io.Writer, format Format) error
	// Batch generates multiple QR codes concurrently, one per payload.
	Batch(ctx context.Context, payloads []payload.Payload, opts ...Option) ([]*encoding.QRCode, error)
	// Close releases resources held by the generator.
	Close(ctx context.Context) error
	// Closed reports whether the generator has been closed.
	Closed() bool
	// SetOptions updates the generator's default options after construction.
	SetOptions(opts ...Option) error
}

Generator is the primary interface for creating QR codes. All generation and rendering operations are performed through this interface. A Generator is safe for concurrent use: its internal configuration is protected by a read-write lock, and duplicate generation requests are deduplicated via a singleflight group.

The typical lifecycle is New, one or more Generate/GenerateToWriter calls, and Close. After Close, all subsequent method calls return an error with code ErrCodeClosed.

gen, err := qrcode.New(qrcode.WithErrorCorrection(qrcode.LevelH))
if err != nil { /* handle error */ }
defer gen.Close(ctx)

qr, err := gen.Generate(ctx, payload.URL("https://example.com")) err = gen.GenerateToWriter(ctx, p, os.Stdout, qrcode.FormatPNG).

func MustNew ¶

func MustNew(opts ...Option) Generator

MustNew is like New but panics on error. Useful in package-level variable initialization where error handling is not practical.

var gen = qrcode.MustNew(qrcode.WithDefaultSize(512))

func New ¶

func New(opts ...Option) (Generator, error)

New creates a new Generator configured with the given options. If no options are provided, sensible defaults are applied: error correction level M, automatic version sizing, 300px image size, 4-module quiet zone, and 4 concurrent workers.

New validates the configuration and returns a wrapped validation error if any option produces an invalid combination (e.g., MinVersion > MaxVersion).

gen, err := qrcode.New(
    qrcode.WithErrorCorrection(qrcode.LevelH),
    qrcode.WithDefaultSize(400),
    qrcode.WithQuietZone(4),
    qrcode.WithLogo("logo.png", 0.25),
)

func QRFromContext ¶

func QRFromContext(ctx context.Context) (Generator, bool)

QRFromContext retrieves a Generator previously stored via ContextWithQR. Returns the Generator and true if found, or nil and false otherwise.

type Option ¶

type Option func(*Config)

Option configures a Generator at construction time. Options are applied to a default Config in the order they are provided, allowing later options to override earlier ones.

Options can also be applied after construction via Generator.SetOptions or Generator.GenerateWithOptions for per-call customization.

gen, err := qrcode.New(
    qrcode.WithErrorCorrection(qrcode.LevelH),
    qrcode.WithDefaultSize(400),
    qrcode.WithLogo("logo.png", 0.25),
)

func WithAutoSize ¶

func WithAutoSize(auto bool) Option

WithAutoSize enables or disables automatic version selection based on data length. When enabled (the default), the encoder automatically picks the smallest QR version that fits the data at the configured error correction level.

func WithBackgroundColor ¶

func WithBackgroundColor(color string) Option

WithBackgroundColor sets the background color as a hex string (e.g. "#FFFFFF"). This color is used for the light modules and quiet zone of the QR code.

func WithConcurrency ¶

func WithConcurrency(n int) Option

WithConcurrency sets the number of concurrent workers. This is an alias for WithWorkerCount provided for API clarity in batch-processing contexts.

func WithDefaultFormat ¶

func WithDefaultFormat(f Format) Option

WithDefaultFormat sets the default output format for rendering. Accepted values are FormatPNG, FormatSVG, FormatTerminal, and FormatPDF.

func WithDefaultSize ¶

func WithDefaultSize(size int) Option

WithDefaultSize sets the default image size in pixels for both width and height. Valid range is 100–4000. The default is 300 pixels.

func WithErrorCorrection ¶

func WithErrorCorrection(level ErrorCorrectionLevel) Option

WithErrorCorrection sets the default error correction level. Higher levels increase damage tolerance but reduce data capacity. Use LevelH when a logo overlay is applied.

func WithForegroundColor ¶

func WithForegroundColor(color string) Option

WithForegroundColor sets the foreground (module) color as a hex string (e.g. "#000000"). This color is used for the dark modules of the QR code. Supports gradients when used together with renderer.WithGradient.

func WithLogo ¶

func WithLogo(logoSource string, sizeRatio float64) Option

WithLogo configures a logo to overlay at the center of the QR code. sizeRatio is the fraction of the QR code image the logo occupies (e.g. 0.25 means the logo width is 25% of the QR image width). Accepted range is 0.05–0.4. When a logo is used, LevelH error correction is strongly recommended.

func WithLogoOverlay ¶

func WithLogoOverlay(enabled bool) Option

WithLogoOverlay enables or disables logo overlay rendering. When enabled, the generator composites the configured logo image onto the center of the QR code. A logo source must be configured via WithLogo or by setting Config.LogoSource.

func WithLogoTint ¶

func WithLogoTint(color string) Option

WithLogoTint applies a tint color to the overlaid logo. The tint is specified as a hex string (e.g. "#1a1a2e") and is applied by multiplying the logo's pixel colors with the tint, producing a colorized overlay that matches the QR theme.

func WithMaskPattern ¶

func WithMaskPattern(pattern int) Option

WithMaskPattern sets the mask pattern to use (0–7). Each mask pattern applies a different XOR formula to the data modules to optimize readability. Set to -1 (the default) for automatic selection, which evaluates all eight patterns and picks the one with the lowest penalty score.

func WithMaxVersion ¶

func WithMaxVersion(v int) Option

WithMaxVersion sets the maximum QR code version the auto-sizer may select (1–40). Useful to limit the physical size of the generated QR code.

func WithMinVersion ¶

func WithMinVersion(v int) Option

WithMinVersion sets the minimum QR code version the auto-sizer may select (1–40). When AutoSize is enabled, the encoder will not choose a version smaller than this.

func WithPrefix ¶

func WithPrefix(prefix string) Option

WithPrefix sets a URI prefix prepended to the encoded payload data. This is useful when the raw encoded output needs to be wrapped in a URI scheme or namespace (e.g. "https://example.com/qr?").

func WithQueueSize ¶

func WithQueueSize(n int) Option

WithQueueSize sets the capacity of the internal work queue (>=1). This option affects the batch.Processor pipeline.

func WithQuietZone ¶

func WithQuietZone(zone int) Option

WithQuietZone sets the number of quiet-zone (margin) modules around the QR code. The quiet zone is the blank border required by QR readers for reliable scanning. Valid range is 0–20; the default is 4.

func WithSlowOperation ¶

func WithSlowOperation(d time.Duration) Option

WithSlowOperation sets the threshold above which a generation is logged as slow. The default is 100ms. Set to 0 to disable slow-operation warnings.

func WithVersion ¶

func WithVersion(v int) Option

WithVersion sets the default QR code version (1–40). When set to a non-zero value, automatic version selection is disabled and the specified version is used for all generations. Pair with WithAutoSize(false) to enforce the version.

func WithWorkerCount ¶

func WithWorkerCount(n int) Option

WithWorkerCount sets the number of worker goroutines for batch generation (1–64). This option affects the Generator.Batch method and the batch.Processor type.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
batch Package batch provides concurrent batch processing for QR code generation with support for file output, JSON/CSV input parsing, and per-item statistics.	Package batch provides concurrent batch processing for QR code generation with support for file output, JSON/CSV input parsing, and per-item statistics.
encoding Package encoding implements the core QR code encoding pipeline including mode selection, data bitstream construction, Reed–Solomon error correction, mask pattern selection, and module matrix construction.	Package encoding implements the core QR code encoding pipeline including mode selection, data bitstream construction, Reed–Solomon error correction, mask pattern selection, and module matrix construction.
errors Package errors provides structured error types for the QR code library.	Package errors provides structured error types for the QR code library.
internal
hash Package hash provides FNV-1a hashing utilities for keys and byte slices.	Package hash provides FNV-1a hashing utilities for keys and byte slices.
lifecycle Package lifecycle provides a concurrency-safe close guard that tracks whether a resource has been closed and signals waiters via a channel.	Package lifecycle provides a concurrency-safe close guard that tracks whether a resource has been closed and signals waiters via a channel.
pool Package pool provides a sync.Pool-backed pool of bytes.Buffer instances to reduce allocations in high-throughput QR code rendering paths.	Package pool provides a sync.Pool-backed pool of bytes.Buffer instances to reduce allocations in high-throughput QR code rendering paths.
singleflight Package singleflight provides a mechanism to suppress duplicate function calls.	Package singleflight provides a mechanism to suppress duplicate function calls.
logo Package logo provides image loading, resizing, tinting, and overlay compositing for QR code center logo images.	Package logo provides image loading, resizing, tinting, and overlay compositing for QR code center logo images.
payload Package payload provides convenience builder functions for constructing validated payload instances.	Package payload provides convenience builder functions for constructing validated payload instances.
renderer Package renderer provides QR code rendering in multiple output formats including PNG, SVG, PDF, terminal Unicode, and base64 with support for custom module styles, gradients, and transparency.	Package renderer provides QR code rendering in multiple output formats including PNG, SVG, PDF, terminal Unicode, and base64 with support for custom module styles, gradients, and transparency.
testing Package testing provides contract tests and test utilities for the QR code library.	Package testing provides contract tests and test utilities for the QR code library.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

README.md - Comprehensive Documentation

QRcode - Feature-rich QR code generation library for Go

Overview

Installation

Quick Start

Usage

Basic Generation

Quick Functions

Generator Interface

Builder Pattern

Payload Types

Text and URL

WiFi

vCard Contact

MeCard

Email

SMS

Phone

MMS

Geo Location

Maps

Calendar Event

Event Ticket

Social Media

WhatsApp

Zoom

Payment

iBeacon

NTP

App Store / Google Play

Swiss QR-Bill (PID)

Rendering Options

Output Formats

Module Shapes

Gradient Fill

Transparency

Complete Styled Rendering Example

Logo Overlay

Error Correction Levels

Options Reference

Core Options

Rendering Options

Logo Options

Concurrency Options

Miscellaneous

Batch Generation

Go Doc Reference

Types

type Config

type ErrorCorrectionLevel

type Format

type Generator

type Option

type Builder

Package-level Functions

Sub-packages

License

Documentation ¶

Overview ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

func ContextWithQR ¶

func GenerateASCII ¶

func GenerateBase64 ¶

func GeneratePNG ¶

func GenerateSVG ¶

func Quick ¶

func QuickContact ¶

func QuickEmail ¶

func QuickEvent ¶

func QuickFile ¶

func QuickGeo ¶

func QuickPayment ¶

func QuickSMS ¶

func QuickSVG ¶

func QuickURL ¶

func QuickWiFi ¶