Customize appearance

Built-in visual renderers share the same styling options, defaults, and validation rules. This guide uses SVG, but the size, quiet-zone, color, module, and finder settings also apply to Canvas, PNG-backed Image, and Node.js PNG output.

Prerequisite

Start with a working renderer. For the recommended default, install @qrcodesdk/core and confirm that the minimal SVG example produces output.

Apply a visual theme

import {QRCodeSVGRenderer, qrcode} from '@qrcodesdk/core';

const svg = qrcode('https://qrcodesdk.dev').render(
  QRCodeSVGRenderer({
    size: 8,
    margin: 4,
    colors: {
      colorDark: '#111827',
      colorLight: '#ffffff',
    },
    dotsOptions: {type: 'rounded'},
    cornersSquareOptions: {type: 'extra-rounded', color: '#7c3aed'},
    cornersDotOptions: {type: 'dot', color: '#2563eb'},
    title: 'QRCodeSDK website',
    ariaLabel: 'Scan to open qrcodesdk.dev',
  }),
);

Shared visual options

Option	Default	Validation and meaning
size	5	Positive safe integer; pixels per module for visual output
margin	4	Non-negative safe integer; quiet zone in modules
colors.colorDark	'#000000'	Hash-prefixed, six-digit hexadecimal color
colors.colorLight	'#ffffff'	Hash-prefixed, six-digit hexadecimal color
dotsOptions.type	'square'	Shape of ordinary dark modules
dotsOptions.color	colors.colorDark	Ordinary-module color override
cornersSquareOptions.type	'square'	Shape of finder outer rings
cornersSquareOptions.color	colors.colorDark	Finder-ring color override
cornersDotOptions.type	'square'	Shape of finder centers
cornersDotOptions.color	colors.colorDark	Finder-center color override

The rendered width and height are size × (matrix width + 2 × margin). For terminal text, size is an integer scale rather than a pixel measurement; see the Terminal text reference.

Module and finder types

Feature	Option	Supported types
Ordinary modules	dotsOptions.type	square, rounded, dots, classy, classy-rounded, extra-rounded
Finder outer rings	cornersSquareOptions.type	all ordinary-module types plus dot
Finder centers	cornersDotOptions.type	all ordinary-module types plus dot

Color overrides are independent. Omitting one keeps that feature on colors.colorDark. Curved shapes are neighbor-aware and raster renderers antialias their edges. Shape options do not change terminal text geometry.

Keep the quiet zone clear

margin is the light quiet zone surrounding the encoded matrix. Keep the default four-module margin unless the destination format adds an equivalent clear border. Do not place text, borders, background art, or adjacent UI inside it.

When reducing the margin for a constrained layout, scan-test the final composition—not only the raw renderer output—at its smallest displayed size.

Add accessible labels

SVG and PNG-backed Image output support title and ariaLabel; Image output also supports alt. Describe the destination or action rather than the visual grid.

QRCodeSVGRenderer({
  title: 'Event registration',
  ariaLabel: 'Scan to open event registration',
});

For a decorative QR code that repeats a nearby link, follow the accessibility semantics of the element or component where you render it. The renderer reference lists the attributes emitted by each output.

Add a center image

SVG, Canvas, PNG-backed Image, Node.js PNG, React, Vue, Svelte, and Angular accept prepared center-image sources, but their source types and loading behavior differ. Follow Add a center image for preparation, sizing, padding, and framework-specific examples.

Protect scan reliability

• Keep every dark feature in strong contrast with colors.colorLight; do not rely on hue difference alone.
• Preserve a clear quiet zone and render modules large enough to survive the final display or print process.
• Prefer conservative shapes when the QR code will be small, compressed, printed, or viewed by older scanners.
• Use .errorCorrection('H') when a center image intentionally covers modules, while remembering that higher redundancy cannot guarantee recovery from an oversized overlay.
• Test the final artifact with the devices, apps, lighting, scale, and compression used in production.

Error correction changes matrix capacity rather than appearance. Its complete definition and the version/mask controls are in Builder and matrix.

Result and next step

The output now uses one shared visual theme without changing its payload. Look up output-specific options in Renderer outputs, or add a prepared logo with Add a center image.