qrgode

qr-gode

A feature-rich QR code generator library for Go with extensive customization options.

Showcase

Classic	Circle	Rounded · linear gradient	Dot · radial gradient
Heart	Star · gradient	Diamond	Dark mode
Logo · classic	Logo · overlay mode

Reproduce these with go run ./cmd/gen-showcase.

Features

• Multiple module shapes (square, circle, rounded, diamond, dot, star, heart)
• Solid colors and gradients (linear & radial)
• Custom images for finder patterns, alignment patterns, and modules
• Logo support with automatic sizing, configurable padding, and exclude/overlay placement modes
• SVG and PNG output — every styling feature works in both formats
• Configurable error correction levels

Installation

go get github.com/ahmedtahas/qr-gode

Quick Start

CLI Usage

# Basic QR code
qr-gode "https://example.com"

# Custom styling
qr-gode -shape circle -fg "#3498db" "Hello World"

# Gradient colors
qr-gode -gradient "#ff6b6b,#4ecdc4" -shape rounded "Gradient QR"

# With a logo
qr-gode -logo logo.png "https://example.com"

# Custom images for patterns
qr-gode -finder-img finder.png -module-img dot.png "Custom QR"

CLI Options

Library Usage

Builder API (Recommended)

The fluent builder API is the simplest way to generate QR codes:

package main

import (
    "os"

    qrgode "github.com/ahmedtahas/qr-gode"
)

func main() {
    // Simple QR code
    svg, err := qrgode.New("https://example.com").SVG()
    if err != nil {
        panic(err)
    }
    os.WriteFile("qr.svg", svg, 0644)
}

Styling Options

// Custom colors and shape
svg, _ := qrgode.New("Hello World").
    Size(512).
    Shape(qrgode.ShapeCircle).
    Foreground("#3498db").
    Background("#ffffff").
    SVG()

// Linear gradient
svg, _ := qrgode.New("Gradient QR").
    Shape(qrgode.ShapeRounded).
    LinearGradient(45, "#ff6b6b", "#4ecdc4").
    SVG()

// Radial gradient
svg, _ := qrgode.New("Radial QR").
    Shape(qrgode.ShapeDot).
    RadialGradient(0.5, 0.5, "#ff6b6b", "#4ecdc4", "#45b7d1").
    SVG()

Adding a Logo

// Auto-sized logo from file (15-30% of QR size, preserves aspect ratio)
svg, _ := qrgode.New("https://example.com").
    Logo("logo.png").
    SVG()

// Logo from in-memory image
svg, _ := qrgode.New("https://example.com").
    LogoImage(myImage). // image.Image
    SVG()

// Custom logo dimensions
svg, _ := qrgode.New("https://example.com").
    Logo("logo.png").
    LogoWidth(100).
    SVG()

// Transparent logo background
svg, _ := qrgode.New("https://example.com").
    Logo("logo.png").
    LogoBackground("transparent").
    SVG()

Custom Pattern Images

// Use custom images for QR elements
svg, _ := qrgode.New("Custom QR").
    FinderImage("finder.png").
    AlignmentImage("alignment.png").
    ModuleImage("module.png").
    SVG()

Error Correction

// Higher error correction for logos or damaged codes
svg, _ := qrgode.New("https://example.com").
    ErrorCorrection(qrgode.LevelH). // 30% recovery
    Logo("logo.png").
    SVG()

Functional Options API

Alternative API using functional options:

svg, err := qrgode.GenerateWithOptions("https://example.com",
    qrgode.WithSize(512),
    qrgode.WithModuleShape("circle"),
    qrgode.WithLogo("logo.png"),
)

Direct Config API

For full control, use the Config struct directly:

cfg := qrgode.DefaultConfig()
cfg.Size = 512
cfg.Modules.Shape = "circle"
cfg.Modules.Color = qrgode.NewLinearGradientColor(45, []string{"#ff6b6b", "#4ecdc4"})
cfg.Logo = &qrgode.LogoConfig{
    Path: "logo.png",
}

svg, err := qrgode.Generate("https://example.com", cfg)

Simple Generate Functions

For quick generation without configuration:

// Generate to bytes
svg, err := qrgode.Generate("https://example.com", nil)

// Generate directly to file
err := qrgode.GenerateToFile("https://example.com", nil, "qr.svg")

Available Shapes

Use the typed Shape constants for type safety:

Error Correction Levels

When adding a logo, consider using LevelQ or LevelH to ensure the QR code remains scannable.

Scannability check

For logo+ECL combinations that are likely to break scanning, call ScannabilityWarnings() and surface the results however you like:

qr := qrgode.New("https://example.com").
    Logo("logo.png").
    ErrorCorrection(qrgode.LevelM)

for _, msg := range qr.ScannabilityWarnings() {
    log.Println("qrgode:", msg)
}

The check is heuristic — print quality, contrast, and scanner camera also affect real-world scannability — but it catches the common mistake of pairing a large logo with a low error-correction level.

Custom Images

Finder Pattern Image

The finder pattern image should be a 7x7 module pattern:

• Outer ring (dark)
• White gap
• Inner 3x3 square (dark)

Alignment Pattern Image

The alignment pattern image should be a 5x5 module pattern:

• Outer ring (dark)
• White gap
• Center dot (dark)

Module Image

Any square image that represents a single dark module.

Logo Handling

• Auto-sizing: By default, logos are scaled to fit within 15-30% of the QR code size
• Aspect ratio: Always preserved - logos are never stretched
• In-memory support: Use LogoImage() to pass an image.Image directly
• SVG logos: Treated as 1:1 aspect ratio, scale perfectly at any size
• Background: White rounded rectangle by default, can be set to transparent

Placement: exclude vs. overlay

// Exclude (default): modules under the logo are skipped — cleaner look,
// the error-correction budget absorbs the loss.
qrgode.New(data).Logo("logo.png") // implicit LogoMode(qrgode.LogoExclude)

// Overlay: render every module and stamp the logo on top. Scanners see
// more data, which helps when print quality varies. Pair with a transparent
// logo background if you want the QR pattern to show through.
qrgode.New(data).
    Logo("logo.png").
    LogoMode(qrgode.LogoOverlay).
    LogoBackground("transparent")

LogoPadding(0.05) tightens the space around the logo (default 0.1, fraction of the logo's longer side).

Examples

Generate to File

// SVG or PNG — chosen from the file extension
err := qrgode.New("https://example.com").
    Shape(qrgode.ShapeCircle).
    LinearGradient(45, "#667eea", "#764ba2").
    Logo("logo.png").
    SaveAs("output.png")

Generate to Bytes

svg, err := qrgode.New("https://example.com").SVG()
png, err := qrgode.New("https://example.com").PNG()

Stream to an io.Writer

// HTTP handler — no intermediate []byte allocation
func handler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "image/svg+xml")
    qrgode.New(r.URL.Query().Get("data")).WriteTo(w)
}

Validate Custom Images

// Validate before using
if err := qrgode.ValidateFinderImage("finder.png"); err != nil {
    log.Fatal(err)
}

if err := qrgode.ValidateLogoImage("logo.png"); err != nil {
    log.Fatal(err)
}

License

MIT License