# QR codes on a dark-mode website

> Dark mode flips your page background, and a transparent-background QR code silently becomes light-on-dark — which many scanners refuse. Give every embedded code its own explicit light card, dark modules on a white rectangle that ignores the theme. If you swap colours per theme, swap both foreground and background so polarity stays dark-on-light.

Source: https://useqr.app/docs/design/qr-code-in-a-dark-mode-website · Last reviewed 2026-08-21 · UseQR is free forever, MIT licensed, no signup.

---

## The failure, precisely

A QR code exported with a transparent background borrows whatever sits behind it. On a
light page that is fine. When `prefers-color-scheme: dark` swaps the page background to
near-black, the same dark modules now sit on a dark ground — and if the modules were
themed to a light colour, the code has become **light-on-dark**: inverted polarity.
Support for inverted codes is patchy across scanner implementations — the details are in
[inverted QR codes](/docs/design/inverted-qr-codes) — so the practical symptom is a code
that works for some visitors and silently fails for others, exactly the pattern described
in [inverted and unreadable](/docs/troubleshooting/qr-code-inverted-and-unreadable).
Nobody tests this, because developers preview in one theme.

## Fix 1: an explicit light card

The robust answer is to make the code's background *its own*, not the page's:

```css
.qr-card {
  background: #fff;          /* literal white — not a theme token */
  padding: 12%;              /* the quiet zone, scaling with the card */
  display: inline-block;
  border-radius: 8px;
}
```

The one rule that matters: **the card's background must not be a variable that flips with
the theme.** A white card on a dark page looks deliberate, gives the decoder its
[quiet zone](/glossary/quiet-zone), and works in every theme without further thought. Why
transparency is a liability in general — email clients, PDFs, unknown embedding contexts —
is covered in [transparent background QR codes](/docs/design/transparent-background-qr-codes),
and the padding arithmetic in [aspect and padding](/docs/design/qr-code-aspect-and-padding).

## Fix 2: mind the currentColor trap

Inline [SVG](/glossary/svg) codes often inherit text colour:

```html
<!-- Trap: modules follow the theme's text colour -->
<svg class="qr"><path fill="currentColor" d="…"/></svg>
```

Dark themes set text to near-white, so the modules turn white — light-on-dark again, or
white-on-white inside a light card. Give modules a literal fill (`fill="#111"`) and the
SVG an explicit background rect. `currentColor` is a fine default for icons and a trap
for QR codes.

## Fix 3: theme the pair, never the polarity

If the design insists the code participate in the theme, swap **foreground and background
together**, keeping dark modules on a light ground in both states:

```css
.qr-card { background: #fff; }
.qr-card svg path { fill: #111; }

@media (prefers-color-scheme: dark) {
  .qr-card { background: #ececec; }  /* softened, still light */
  .qr-card svg path { fill: #111; }  /* polarity unchanged */
}
```

An off-white card reads gentler on a dark page and still clears the **40% luminance
difference** with room to spare. What must never happen is the naive swap — light modules
on the dark page — which is the inverted failure with extra steps.

## Remember who scans it

A code on a website is scanned by a phone pointed at a monitor
([the mechanics have their own quirks](/docs/scanning/scanning-a-qr-code-off-a-monitor))
or decoded [from a screenshot](/docs/scanning/how-to-scan-a-qr-code-from-a-screenshot) —
and the screenshot preserves whichever theme the visitor had. Test both themes with a
real phone, and run a screenshot of each through the [validator](/validate); it takes two
minutes and catches the failure the preview never shows.

## FAQ

### Why does my QR code not scan in dark mode?

Almost certainly polarity: a transparent or theme-coloured code has become light modules
on a dark background, and many scanners only reliably decode dark-on-light. Put the code
on an explicit white card that does not change with the theme.

### Should a QR code invert its colours in dark mode?

No. Keep dark modules on a light background in both themes. If the pure white card feels
harsh on a dark page, soften it to a light grey — the polarity and the 40% luminance
difference are what must survive the theme switch.

### Is currentColor safe for SVG QR codes?

No. currentColor follows the theme's text colour, so dark themes silently turn the
modules light. Give the module paths a literal dark fill and the SVG an explicit light
background rectangle.

### How do I test a QR code in both themes?

Toggle prefers-color-scheme in the browser's dev tools, scan the rendered page from a
phone in each theme, and decode screenshots of both with a QR validator. The failure only
appears in the theme you did not design in.

## Try it

- https://useqr.app/url
- https://useqr.app/validate