QR code colour inversion and polarity

What the specification actually says

ISO/IEC 18004 defines a QR symbol in terms of dark modules on a light background, the nominal form every conformant encoder produces and every conformant decoder must read. "Dark" and "light" are reflectance roles, not specific colours: navy on cream is fine, as long as the modules reflect less light than the background by a healthy margin (the working rule is a luminance difference of at least 40%, covered on QR colours that scan).

The crucial detail: nothing inside the symbol records its polarity. There is no flag in the format information saying "this one is inverted". A light-on-dark code is, from the standard's viewpoint, simply a photographic negative of a QR code, not an alternate valid form of one.

Inverted reading is a decoder heuristic

Because polarity is not signalled, a decoder that reads inverted codes does so by guessing: it fails to find finder patterns in the normal polarity, inverts the image, and tries again. Support is therefore a property of the scanner, not the code:

• ZXing, the most widely embedded open-source decoder, treats inversion as an explicit option (tryInvert in current zxing-wasm builds), hosts that leave it off simply do not read inverted codes.
• Recent iOS and Android cameras generally handle inversion in practice.
• Embedded scanners (payment terminals, access-control readers, warehouse guns, kiosk webcam software) are the long tail where inverted reads most often fail, because they run one decode pass, tuned for the nominal form, on limited hardware.

That asymmetry is the trap: an inverted code passes the designer's own phone test and then fails quietly in the field on scanners nobody thought to try. You will not get a crisp failure rate for "the field" (it depends entirely on which devices your audience carries), which is itself the argument: you cannot bound the loss, only avoid it.

The rule, and the escape hatches

Print dark modules on the lighter colour. On a dark background, the standard-compliant move is not to invert the modules but to give the code its own light panel: a white or pale rounded rectangle behind the full symbol, including the four-module quiet zone, with the dark modules on top. The design patterns for dark layouts, including dark-mode websites, are on inverted QR codes and why light-on-dark QR codes fail.

Note that the quiet zone's polarity must match the background role: a dark-on-light code needs a light quiet zone. Inverting the modules but leaving a white margin (a common half-inversion from design tools) fails both polarities at once.

If you have inherited an inverted code that will not read, the recovery steps are on QR code inverted and unreadable. And whichever way you go, /validate reads your rendered artwork back with a real decoder, the only polarity opinion that counts.

FAQ

Can a QR code be white on black?

Sometimes (many modern phone cameras invert the image and retry), but support is a per-scanner heuristic, not part of the standard, and embedded scanners frequently fail. If you cannot test every scanner your audience uses, keep dark modules on a light background.

Why does my inverted QR code scan on iPhone but not on other devices?

Recent phone cameras retry the decode on an inverted copy of the image; many other decoders run a single pass expecting dark-on-light and give up. The code did not change between devices: the guessing strategy did.

Does a QR code store whether it is inverted?

No. The format information records error correction level and mask pattern only; there is no polarity flag anywhere in the symbol. An inverted code is just a negative image, which a decoder may or may not think to try.

How do I put a QR code on a dark design without inverting it?

Give the code a light panel (white or a pale brand tint) covering the full symbol plus its four-module quiet zone, and print normal dark modules on that. It reads on effectively every scanner and still sits comfortably in a dark layout.