How QR codes work
A QR code is a square grid of dark and light modules:
- Fixed patterns help a scanner find and orient the code.
- The remaining modules carry the payload, error correction data, and format information.
Change the payload and options below, then select a region or a single module to see its role. Both standard and Micro QR codes are supported. rMQR codes are not explained here.
Turn on Show encoding trace to see how the encoder filled the symbol: the segments and their bit costs, the terminator and padding, the error correction blocks, the codewords in placement order, and the score of every mask. With the trace on, a module’s details also name its codeword and the part of the bit stream it carries. The trace is part of this page, not a QRCodeSDK API.
Configure
QR anatomy
Hover to preview · click to pin
Inspect a module
Hover a module to see its role. Click, tap, or press Enter to pin it.
Modules and versions
Section titled “Modules and versions”Each square in the grid is a module. The version sets the grid size:
- Version 1 is 21 × 21 modules.
- Each version adds 4 modules per side.
- Version 40 is 177 × 177 modules.
A larger version holds more data. At the same printed size, its modules are smaller.
Scanners also need a light border around the code, the quiet zone. The QR code standard asks for
four modules. QRCodeSDK renderers default to quietZone: 4.
Function patterns
Section titled “Function patterns”Function patterns sit in the same place in every symbol of a version, whatever the payload:
- Finder patterns are the three 7 × 7 squares in the corners. Their 1:1:3:1:1 ratio of dark and light modules lets a scanner find the code and its rotation from any angle.
- Separators are light borders, one module wide, around each finder pattern.
- Timing patterns are alternating dark and light modules between the finders. They let the scanner measure the module grid.
- Alignment patterns are 5 × 5 squares that appear from version 2. They help the scanner correct perspective and bent surfaces. Larger versions have more of them.
- Format information stores the error correction level and the mask, twice, next to the finders.
- Version information stores the version number in two more areas, from version 7.
In QRCodeSDK:
QRCodeMatrix.rolestells you the role of every module.finder()andalignment()restyle the finder and alignment patterns without changing their modules.
Encoding the payload
Section titled “Encoding the payload”The payload is split into segments. Each segment holds:
- A mode indicator.
- A character count.
- The characters, packed for that mode.
| Mode | Characters | Payload bit cost |
|---|---|---|
| Numeric | Digits 0–9 |
About 3.33 per digit |
| Alphanumeric | Digits, uppercase A–Z, space, and $%*+-./: |
5.5 per character |
| Octet | Any bytes; QRCodeSDK encodes text as UTF-8 | 8 per UTF-8 byte |
| Kanji | Double-byte Shift JIS characters, such as 漢字 |
13 per character |
In octet mode, one character can take several bytes. é takes 2 UTF-8 bytes, ✅ takes 3, and most
emoji take 4. So one character costs 8 to 32 bits.
Numeric and alphanumeric modes pack text more densely, so the same payload can fit a smaller version. Kanji mode does the same for Japanese text, which takes 24 bits per character in UTF-8. It needs the opt-in Kanji table. By default, QRCodeSDK picks one mode for the whole payload. Two options change the bit stream:
- The optional mixed-mode segmenter combines modes when that makes the bit stream shorter.
- An optional ECI header declares UTF-8, so scanners do not guess the text encoding.
After the segments, a terminator and padding fill the remaining data capacity:
- The terminator is 4 zero bits. When fewer bits are left, it is cut short.
- Alignment zeros complete the last partly used byte.
- Pad codewords
ECand11alternate until the data capacity is full.
Why a payload needs a larger version
Section titled “Why a payload needs a larger version”The version depends on the bits the segments need, not on the length of the string. Each segment
costs its mode indicator, its character count indicator, and its packed characters. For example, at
level M version 1 holds 128 data bits:
| Payload | Mode | Bits needed | Version |
|---|---|---|---|
| 34 digits | Numeric | 4 + 10 + 114 = 128 | 1 |
| 35 digits | Numeric | 4 + 10 + 117 = 131 | 2 |
https://qrcodesdk.dev |
Octet | 4 + 8 + 21 × 8 = 180 | 2 |
https://qrcodesdk.dev and ECI |
Octet | 12 + 4 + 8 + 21 × 8 = 192 | 2 |
One more digit pushes the payload past version 1, so the builder picks version 2, which holds 224
data bits at level M. A higher error correction level leaves fewer data bits in every version.
Character count indicators widen at versions 10 and 27, so the same segments cost a few more bits in
larger versions. In octet mode, the count is the number of UTF-8 bytes, so é✅😀 counts 9 bytes,
although the string has 4 UTF-16 code units.
If you request a version, the builder uses it even when a smaller version would hold the payload.
Error correction
Section titled “Error correction”The data is split into 8-bit codewords. Reed-Solomon error correction codewords are added. They let a scanner restore codewords that are damaged, dirty, or covered:
| Level | Approximate share of codewords that can be restored |
|---|---|
L |
7% |
M |
15% |
Q |
25% |
H |
30% |
Higher levels leave less room for data, so the same payload may need a larger version.
Larger versions split the codewords into several blocks of almost equal length, and each block
gets its own error correction codewords. Blocks of one more data codeword come last. Version 5 at
level Q, for example, has two blocks of 15 and two blocks of 16 data codewords, each with 18 error
correction codewords.
- QRCodeSDK defaults to
M. - Use
Hwhen a center image covers modules. - The builder picks the smallest version that fits the payload at the chosen level.
Placement and masking
Section titled “Placement and masking”The codewords are interleaved before placement: the first data codeword of every block, then the second of every block, and so on. The error correction codewords follow in the same way. A damaged area of the symbol then hits a few codewords of many blocks instead of many codewords of one block.
The bits are placed in two-module-wide columns, zigzagging up and down from the bottom-right corner and skipping the function patterns. In some versions a few remainder bits are left over at the end of the path; they stay zero.
Some layouts confuse scanners: long runs of one color, large blocks, or shapes that look like finder patterns. To avoid them, the encoder masks the data:
- It inverts data modules with each of eight mask patterns.
- It scores each candidate with four penalty rules and keeps the lowest score.
- It records the chosen mask in the format information.
When two masks score the same, the encoder keeps the lower mask number. A scanner reads the mask and
removes it before decoding. QRCodeSDK picks the mask automatically. Pin mask only for fixtures or
compatibility tests.
The mask changes which modules are dark, not how many codewords fit, so it never changes the size of the symbol.
Micro QR codes
Section titled “Micro QR codes”Micro QR codes follow the same steps with a few differences:
- One finder pattern, timing patterns along the top row and left column, and one copy of the format information. The format information stores a symbol number for the version and error correction level, and the mask.
- One segment, one error correction block, and no interleaving.
- Mode indicators are 0 to 3 bits long; M1 has none because it only supports numeric mode. The terminator is 3, 5, 7, or 9 zero bits for M1 to M4.
- M1 and M3 end their data with a 4-bit codeword. Its zero low nibble counts for error correction but is not placed in the matrix.
- M1 only detects errors and has no error correction level.
- There are four masks. The encoder counts the dark modules along the right column and the bottom row, excluding the timing patterns. The score is 16 × the smaller count plus the larger count, and the highest score wins.
Learn more
Section titled “Learn more”- Builder and matrix documents modes, ECI, error correction, versions, and masks as options.
- Custom renderers shows how to draw a matrix with its module roles.
- Customize appearance explains which styling keeps a code scannable.
- Compare with other libraries puts these features next to other JavaScript QR code libraries.