QR Code Generator

A QR code is a grid of black and white squares that holds bytes, and nothing else. Joining a network, adding a contact, opening a link: none of that is in the standard. Every one of those behaviours is a convention layered on top of a code that only ever held bytes.

What the picture is made of

+-----+        +-----+    the three big squares are finder
| ### |........| ### |    patterns: they tell a scanner where
| #   |        |   # |    the code is and which way up
+-----+        +-----+
   :                       the dotted lines are the timing
   :              +---+    pattern, which sets the module size
+-----+           | # |
| ### |           +---+    the small square is an alignment
| #   |                    pattern, correcting for a code
+-----+                    photographed at an angle

Only some of a QR code is your data. The three corner squares are finder patterns, and a scanner looks for their distinctive 1:1:3:1:1 ratio of dark to light in any direction. That is how it reads a code upside down, at an angle, or reflected in a window. The dotted lines running between them are the timing pattern, which tells the scanner how wide one module is. From version 2 onward there are alignment patterns as well, correcting for the distortion of a code photographed off-axis or printed on something curved.

Fifteen bits beside the top-left finder hold the format information: the error correction level and which of eight mask patterns was applied. Those fifteen bits are themselves error-corrected, and stored twice, because a code whose format information is unreadable is a code that cannot be read at all.

Error correction, and why it is not optional

L   ~7% recoverable    holds the most
M  ~15%                the usual choice
Q  ~25%
H  ~30%                holds the least, survives the most

The percentage is of the codewords, not of the area, and
it is what makes a code with a logo stamped in the middle
still work.

QR codes use Reed-Solomon, the same family of code that kept CDs playing through fingerprints. The data is split into blocks, each block gets a set of correction codewords, and the blocks are then interleaved across the whole image so that a scratch, a coffee ring or a sticker damages a little of every block instead of wiping out one of them completely.

This is what lets people put a logo in the middle of a code. It is not a feature, it is spare capacity being spent. At level H roughly 30% of the codewords can be lost, so a mark covering under a fifth of the area is usually safe. Cover a third and it stops working, and it stops working for some phones before others, which is a miserable thing to discover from printed material.

Level M is the right default for anything read off a screen. Go to Q or H for anything printed, put outdoors, or applied to a curved surface.

Size, and how to keep it down

version 1     21x21 modules     17 bytes at level L
version 10    57x57            271
version 25   117x117          1273
version 40   177x177          2953

Every version adds four modules a side. The jump from
one version to the next is what makes a code suddenly
look twice as dense for one more character.

There are forty versions, from 21 modules a side to 177. The generator picks the smallest that fits, so the way to a smaller, more forgiving code is always to put less in it.

Three things help. Drop https:// and www. where you can, since most scanners assume the scheme. Keeping it is safer for anything printed, mind. Use capitals in the path if you control the URL, because a code containing only digits, capital letters and a handful of punctuation marks switches to a denser mode that stores two characters in eleven bits instead of one in eight. And if the URL is long, shorten it, though that means the code now depends on a third party staying in business.

The quiet zone is part of the code

The specification requires four modules of blank space on every side. It looks like a margin you could trim, and trimming it is one of the most common reasons a code that scanned in a design tool fails on a printed page. The blank border is how the scanner finds the edge; without it, a busy background runs straight into the finder patterns.

Colour and contrast

Cameras read luminance, not hue. Dark on light works, light on dark fails on a meaningful fraction of readers because they assume the finder patterns are dark, and two colours of similar lightness fail on all of them however different they look to a person. If you are going to brand a code, change the dark colour and keep the background white, and check the result on a phone that is not yours before it goes to print.

Wi-Fi, contacts and the rest

WIFI:T:WPA;S:Coffee Shop;P:flatwhite;;

T   WPA, WEP or nopass
S   the network name, exactly, capitals and all
P   the password
H   true, if the network is hidden

Backslash-escape any \ ; , : or " inside a value.

None of these formats are in the QR specification. The Wi-Fi string above is a ZXing convention that Android and iOS both adopted; contact cards use vCard 3.0, which is a real standard but not a QR one; calendar events use a bare VEVENT without its usual VCALENDAR wrapper because phone cameras accept it and it saves thirty characters.

Text messages are the messiest. RFC 5724 says sms:, and roughly half of readers ignore it, so what is generated here isSMSTO:number:message. It is the older ZXing form and the one that works nearly everywhere.

A Wi-Fi password typed above is never written into this page's address bar or stored on this device, unlike every other setting here. Sharing the link will share the network name and not the password.

These codes do not expire

A QR code is a picture of some bytes. It has no owner, no account, no server and no expiry, and once printed it will keep resolving to the same string forever.

That is worth saying because a great many QR generators produce a code pointing at their own domain, which redirects to yours. It lets them count scans and change the destination later, and it also means your printed material stops working the day they go under, change their pricing, or decide your free plan has expired. If you want analytics, put the tracking parameters in your own URL and encode that.

Scanning one

There is no reader here, on purpose. Reading a code means access to your camera, and a page that only ever draws pictures does not need that permission. Every phone camera app has done it natively since about 2018.