React library
Round the background, add a halo or a shadow
Round the background's corners with a color around them, rim the dots with a light halo, and give the dots a shadow, within the ranges that keep every look scannable.
Three props change what sits around the dots and eyes without changing the dots themselves: bgRadius (with backdrop) rounds the background, halo rims every dark shape with a light edge, and shadow draws a see-through copy of the dark shapes under them. Each has a range the package's decode tests cover at three phone distances, and the engine keeps a value inside it, so a look never costs a scan on a light surface.
Designing in the playground instead? They are the Rounded corners, Halo and Shadow sections of the Design tab.
Rounded corners
bgRadius rounds the background's corners. It is a share of the code's width, from 0 (square, the default) to BG_RADIUS_MAX (0.5). backdrop is a solid color drawn outside the rounded corners; without it they are see-through, so a PNG or SVG placed on a page shows the page there.
import { QRCode } from "qrdx";
export function RoundedCode() {
return (
<QRCode
value="https://example.com"
size={256}
margin={4}
bgColor="#fff7ed"
bgRadius={0.2}
backdrop="#1e3a8a"
/>
);
}- The arc never reaches the code. The engine caps the radius at
BG_RADIUS_QUIET_RATIO(2) timesmarginmodules, so a code without a margin stays square, and with a margin of 4 a version 2 code rounds up to about a quarter of its width.getBgRadiusLimit({ value, level, margin })returns the cap for a slider. - A circle, heart or silhouette code has its own outline and ignores
bgRadius. - SVG, PNG, JPG, WebP, PDF and EPS downloads keep the rounding and the backdrop; the print PDF's bleed continues the backdrop.
QRCodeCanvasdraws both too.
Halo
halo draws a light rim around every dark module and eye: { color, width }, with width in modules from HALO_WIDTH_MIN (0.1) to HALO_WIDTH_MAX (0.5, default 0.25) and color a solid color (default #e5e7eb, a light grey). The eye frames fill their hole with it too, so the light ring inside each eye stays clean. It is drawn only on an opaque background at least as light as HALO_LIGHT_MIN (#d1d5db), and in a rim decoders read no lighter than the background and at least as light as #d1d5db: a pale tint around dark dots on a white or light background. Any color can be given: one outside that range is drawn in the closest color inside it, with its hue kept and only its lightness moved, so a dark red becomes a pale rose (fitHaloColor(color, bgColor) returns the color drawn).
import { QRCode } from "qrdx";
export function HaloCode() {
return (
<QRCode
value="https://example.com"
size={256}
margin={4}
halo={{ color: "#fde68a", width: 0.3 }}
/>
);
}- A halo is a look, not a quiet zone: keep
margin. - Where it is drawn, it doesn't cost a decode: at the rule's edges (a
#d1d5dbrim on white and on#e5e7eb, with black, grey and blue dots, and on a white to#e5e7ebgradient) every dot shape at widths 0.1, 0.3 and 0.5 reads wherever it reads without one, at 4, 6 and 9 pixels per module, through jsQR and ZXing drawn sharp, and at the widest halo through the camera model (the package's decode tests; the measurements behind the rule covered every width in steps of 0.05 to 0.1). - A rim lighter than what's around the dots makes decoders misread light modules: on a grey page under a see-through code at every width, and with grey or blue dots even as a white rim on
#d1d5db. So a rim color darker than#d1d5dbor lighter than the background (to either decoder's grey: jsQR's and ZXing's weigh red, green and blue differently) is adjusted, not refused: the engine draws the closest color inside the range, and the scan score passes itshalocheck and names the color drawn. Those adjusted rims are tested too: a dark red, blue, green, black and the dots' own color picked for blue dots on white and on#e5e7eb, and a dark red for black dots and on rounded corners over a dark backdrop, read wherever the code reads without a halo, for every dot shape at the same widths and sizes through jsQR and ZXing. The playground's Halo section shows the color drawn next to the one picked ("Drawn as #FFC9CF so the code still scans") and offers tints of the dots' color that are drawn as they are (haloTints(color, bgColor)). - It isn't drawn on a see-through background (any alpha below 1 in
bgColor, a gradient stop included), on a picture background, or on a background darker than#d1d5db, where no rim color would scan. The engine then draws the code without it and the scan score fails ahalocheck with the reason (getHaloRisk); the playground's Halo section says "Won't scan here" and why, and its switch still turns the halo off. While a halo is on, the playground's background color offers no opacity or picture. - The rim is always opaque (a see-through
colorloses its alpha), so the print PDF and EPS, which paint each shape on its own, match the SVG, with the same round corners.QRCodeCanvasignores the halo.
Shadow
shadow draws a see-through copy of the dark modules and eyes under them, shifted by dx and dy modules (each from -SHADOW_OFFSET_MAX to SHADOW_OFFSET_MAX, that is -0.3 to 0.3, default 0.2), in a solid color (default black) at opacity (SHADOW_OPACITY_MIN 0.1 to SHADOW_OPACITY_MAX 0.4, default 0.3). Every dot shape decodes at the strongest setting through the camera model.
import { QRCode } from "qrdx";
export function ShadowCode() {
return (
<QRCode
value="https://example.com"
size={256}
bodyPattern="rounded"
shadow={{ dx: 0.2, dy: 0.2, opacity: 0.3 }}
/>
);
}- A shadow with
dxanddyboth 0 draws nothing. - The print PDF keeps the opacity; EPS has no transparency, so the shadow is mixed with the background.
QRCodeCanvasignores it. - With Logo QR or Image QR art the dots are the picture, so only the eyes get a halo or a shadow.
In the API and MCP
The image API, POST /v1/codes and the MCP tools take the same fields in style: bgRadius, backdrop, halo and shadow, with colors as hex, rgb()/hsl() or a color name. See the image API and the MCP server.
Related
Was this page helpful?
Last updated on
Set colors and gradients
Color the modules, eyes and background with solid colors, linear, radial or angular gradients, see-through colors or image fills, and check it still scans.
Add a logo in code
Put a logo in the center of a QR code with the logo and logoOptions props, size and place it, crop it, give it a plate, and keep the code scannable.