QR Styling Options Reference

The single and bulk generation endpoints accept six optional styling objects that give you the same design control as the visual editor. All of them are strict: unknown fields return a 400 error.

A fully-styled request looks like this:

{
  "data": "https://example.com",
  "width": 1024,
  "height": 1024,
  "margin": 16,
  "shape": "square",
  "image": "https://example.com/logo.png",
  "qrOptions": { "errorCorrectionLevel": "H" },
  "imageOptions": { "imageSize": 0.3, "hideBackgroundDots": true, "margin": 8 },
  "dotsOptions": { "type": "rounded", "color": "#111827" },
  "cornersSquareOptions": { "type": "extra-rounded", "color": "#4f46e5" },
  "cornersDotOptions": { "type": "dot", "color": "#4f46e5" },
  "backgroundOptions": { "color": "#ffffff", "round": 0.1 }
}

qrOptions

Controls the QR encoding itself.

• errorCorrectionLevel — "L", "M", "Q", or "H". Higher levels survive more damage (and logo overlap) at the cost of denser codes. Use "H" whenever you embed a logo.
• typeNumber — 0–40. The QR version (module density); 0 picks the smallest version that fits automatically. Leave at 0 unless you need fixed dimensions across many codes.
• mode — "Numeric", "Alphanumeric", "Byte", or "Kanji". Auto-detected in practice; set it only if you know you need to.

imageOptions

Applies when a logo image is provided.

• imageSize — 0.05–1, the logo's size as a fraction of the QR code. Around 0.3 is a safe maximum with errorCorrectionLevel: "H".
• hideBackgroundDots — true removes the QR dots behind the logo so it sits on a clean area.
• margin — 0–100, padding in pixels around the logo.
• crossOrigin — CORS mode used when fetching a logo URL.

dotsOptions

Styles the data dots — the body of the code.

• type — "square", "dots", "rounded", "extra-rounded", "classy", or "classy-rounded".
• color — hex or CSS color.
• gradient — a gradient instead of a flat color (see below).
• roundSize — boolean; rounds the computed dot size to whole pixels for crisper rendering.

cornersSquareOptions and cornersDotOptions

Style the three large finder patterns (cornersSquareOptions is the outer ring, cornersDotOptions the inner dot).

• type — "square", "dot", "dots", "rounded", "extra-rounded", "classy", or "classy-rounded".
• color / gradient — same as dots.

backgroundOptions

• color / gradient — the background fill.
• round — 0–1, rounds the background's corners (as a fraction of size).

Gradients

Anywhere a color is accepted, a gradient object can be used instead:

{
  "type": "linear",
  "rotation": 0,
  "colorStops": [
    { "offset": 0, "color": "#111827" },
    { "offset": 1, "color": "#4f46e5" }
  ]
}

• type — "linear" or "radial".
• rotation — rotation of a linear gradient, in radians.
• colorStops — 2 to 10 stops, each with an offset from 0 to 1 and a color.