Styling and colors

Every visual decision boils down to a few parameters: color, background, pattern, eye styling, optional gradient, optional frame, and the optional logo. This page covers everything except the logo, which has its own page.

color

Sets the color of the modules (the dark squares) and, by default, the finder patterns (the three big squares in the corners).

{ "color": "black" }
{ "color": "#6c48e8" }
{ "color": "#3a1478ff" }

warning: Contrast matters for scannability Modules must contrast sharply with the background. Aim for at least a 3:1 luminance ratio. Light gray on white is unscannable.

background

The card the QR sits on.

Transparent backgrounds

Set background: "transparent" for the cleanest results. The PNG keeps its alpha channel; SVG omits the background <rect>. Drop it on a photo, t-shirt, sticker, only the modules and your logo show.

tip: Pair color with substrate

• White modules + transparent + dark t-shirt = clean print
• Black modules + transparent + photo = elegant overlay
• White modules + transparent + black sticker = signage classic

pattern

The shape of each module.

The finder patterns (the three corner squares) always stay square. The QR spec requires the 1:1:3:1:1 ratio for ratio detection. Rounding them breaks scanning on industrial decoders.

eye styling

The "eyes" are the three finder patterns. They have an outer ring and an inner pupil that you can style independently.

eye_border_shape accepts square, rounded, circle, leaf-tl, leaf-tr, leaf-br, leaf-bl, frame. eye_center_shape accepts square, rounded, circle, leaf-tl, sunburst, star, diamond, cross.

warning: Decoder safety Highly stylized eyes (especially asymmetric leaf shapes) can fail on industrial scanners. Before printing 10 000 stickers, test with a cheap warehouse barcode reader and at least two phone models.

gradient

Vertical 2-stop gradient on the body modules. Both stops must be set together.

{
 "gradient_from": "#6c48e8",
 "gradient_to": "#1a0d3a"
}

The eye color is independent and is never a gradient: scanners need solid eyes for ratio detection.

frame_style

Decorative frame painted around the QR. The QR shrinks to fit so scanability is preserved (the frame never overlaps the matrix).

Each accepts frame_color and frame_label_color for theming, plus a frame_label (max 24 chars) that prints inside the "Scan me" tab.

{
 "frame_style": "scan-me-bottom",
 "frame_color": "#6c48e8",
 "frame_label": "Scan to view menu",
 "frame_label_color": "#ffffff"
}

bg_image_url

Pair with pattern: "halftone" to paint a photo under the modules at reduced opacity (bg_image_opacity default 0.35). The halftone pattern makes the photo "show through" the dots while keeping the QR scannable.

{
 "data": "https://yourbrand.com",
 "size_inches": 6,
 "pattern": "halftone",
 "bg_image_url": "https://cdn.yourbrand.com/cover.jpg",
 "bg_image_opacity": 0.4,
 "color": "#1a0d3a"
}

bg_image_url is fetched server-side with the same SSRF protection as logo_url (see Security model).

Combining everything

Brand kit (dark substrate)

{
"data": "https://yourbrand.com",
"size_inches": 8,
"color": "white",
"background": "transparent",
"pattern": "rounded",
"eye_shape": "circle",
"logo_clear_zone": true
}

Outcome: pure white modules on transparent. Drops on dark t-shirts, photos, posters. Logo hole transparent.

Print on white card stock

{
"data": "https://yourbrand.com",
"size_inches": 4,
"color": "black",
"background": "white",
"pattern": "rounded"
}

Outcome: standard high-contrast print. Cheapest to produce.

Brand-colored gradient

{
"data": "https://yourbrand.com",
"size_inches": 4,
"background": "white",
"pattern": "rounded",
"gradient_from": "#6c48e8",
"gradient_to": "#1a0d3a",
"eye_color": "#1a0d3a"
}

Outcome: top-to-bottom purple gradient on body, solid dark eyes.

Halftone over a photo

{
"data": "https://yourbrand.com",
"size_inches": 6,
"background": "white",
"color": "#0d0820",
"pattern": "halftone",
"bg_image_url": "https://cdn.yourbrand.com/coffee.jpg",
"bg_image_opacity": 0.45
}

Outcome: variable-opacity dots, photo subtly visible behind them.

Inverted scan-me poster

{
"data": "https://yourbrand.com",
"size_inches": 8,
"color": "white",
"background": "black",
"pattern": "rounded",
"frame_style": "scan-me-bottom",
"frame_color": "#6c48e8",
"frame_label": "Free Wi-Fi",
"frame_label_color": "#ffffff"
}

Outcome: white-on-black with a purple "Free Wi-Fi" tab.

Common mistakes

danger: Light-on-light or dark-on-dark Pale gray modules on white, or navy on black, will not scan. Do not trust your eyes; calculate luminance contrast or stick to black/white for safety.

danger: Over-saturated brand colors Bright neon green / cyan / yellow on white sometimes fails on older scanners. Test on at least three phones before mass production.

danger: Patterns inside finders Stylized finders are tempting visually, but they break the 1:1:3:1:1 ratio detector. The QR may scan on iPhones (which forgive a lot) but fail on industrial scanners.

What is next

• Logos: add your brand to the center
• Print quality guide: DPI, sizes, files
• API reference: every parameter