# Round the background, add a halo or a shadow (Features)

URL: https://qrdx.dev/docs/features/effects
Source: https://github.com/qrdxinc/qrdx/blob/main/apps/docs/content/docs/features/effects.mdx

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 [#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.

```tsx title="components/rounded-code.tsx"
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) times `margin` modules, 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. `QRCodeCanvas` draws both too.

## Halo [#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).

```tsx title="components/halo-code.tsx"
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 `#d1d5db` rim on white and on `#e5e7eb`, with black, grey and blue dots, and on a white to `#e5e7eb` gradient) 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 `#d1d5db` or 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 its `halo` check 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 a `halo` check 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 `color` loses its alpha), so the print PDF and EPS, which paint each shape on its own, match the SVG, with the same round corners. `QRCodeCanvas` ignores the halo.

## Shadow [#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.

```tsx title="components/shadow-code.tsx"
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 `dx` and `dy` both 0 draws nothing.
- The print PDF keeps the opacity; EPS has no transparency, so the shadow is mixed with the background. `QRCodeCanvas` ignores 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 [#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](https://qrdx.dev/docs/developers/image-api#style) and the [MCP server](https://qrdx.dev/docs/developers/mcp).

## Related [#related]

- [Choose module and eye shapes](https://qrdx.dev/docs/features/patterns): Dot shapes, eye shapes, per-eye shapes and the dot size.
- [Set colors and gradients](https://qrdx.dev/docs/features/colors-gradients): Colors, gradients, see-through colors and image fills.
- [Export and download](https://qrdx.dev/docs/features/downloads): Which formats keep transparency and see-through colors.
