Surface guide
QR codes on websites
A QR code on a web page is scanned by a second device pointed at the screen. Size it at 150–250 CSS pixels, serve SVG, and remember that on mobile the code is nearly useless — a tap target is better.
| Typical scan distance | screen |
|---|---|
| Minimum code width | 150–250 px |
| Error correction | M |
On mobile, use a link instead
Someone on a phone cannot scan a code on their own screen. Detect the viewport and show a plain link on small screens, the code on large ones. Showing both is fine; showing only the code is a broken experience for half your traffic.
Serve SVG
An SVG QR code is a couple of kilobytes, renders crisply at any zoom, and costs no extra
request if inlined. shape-rendering: crispEdges prevents anti-aliasing artefacts.
Dark mode
A QR code with a transparent background inverts on a dark page and becomes unreadable on many scanners. Give it an explicit light background — a white rounded panel behind the code is the safe pattern in both themes.
Accessibility
alt text describing the destination, not the mechanism: alt="QR code linking to the download page". Screen-reader users need the link itself, so always render a real anchor
alongside.
Do not use an image API you do not control
Hotlinking a third-party QR image service means every page view depends on their uptime and leaks your visitors' requests to them. Generate at build time and serve it yourself, or use a keyless API you can cache.