QR code aspect ratio and padding

Square, full stop

Every QR code is a square grid of square modules, 21×21 for version 1 up to 177×177 for version 40. Decoders do invert perspective distortion (a code viewed at an angle is geometrically similar to a stretched one), so a mildly stretched code often still scans, but you are spending the same tolerance budget that real-world camera angles need, for zero benefit. Heavily stretched codes fail outright. Never set width and height independently; if a layout slot is genuinely wide and short, the honest answer is rMQR, a rectangular format designed for exactly that: see rectangular Micro QR, not a squashed QR code.

Padding is the quiet zone

What designers call padding, the specification calls the quiet zone: at least 4 modules of clear background on every side. The critical property is that it is measured in modules, so it must scale with the code:

• A 25-module code rendered at 250 px has 10 px modules → padding ≥ 40 px.
• The same code at 100 px has 4 px modules → padding ≥ 16 px.
• A version 10 code (57 modules) at 250 px has ~4.4 px modules → padding ≥ 18 px.

A fixed padding: 10px in a stylesheet is therefore wrong twice over: too little for large renders, and wrong again when the payload changes and the module count with it. If you cannot know the version, pad 20% of the code's width per side: that covers the worst case (version 1, where 4 modules is 19% of the code) and every larger version. What happens when this margin is shaved is catalogued in quiet zone too small.

The CSS that breaks codes

/* Breaks codes: crops edges and quiet zone to fill the box */
img.qr { width: 100%; height: 180px; object-fit: cover; }

/* Safe: square box, contained image, own light background */
img.qr {
  width: 100%;
  max-width: 320px;
  aspect-ratio: 1 / 1;
  object-fit: contain;
  background: #fff;
  padding: 12%;
  box-sizing: border-box;
}

The recurring offenders:

• object-fit: cover in a non-square box crops the code's edges: the quiet zone first, then finder patterns. contain or an aspect-ratio: 1 / 1 box is the fix.
• Independent height (height: 180px with fluid width, or align-items: stretch in a flex row) silently distorts the grid.
• border-radius on a tight container clips the corners exactly where the finder patterns sit; harmless only if the padding already exceeds the rounding.
• Filters and opacity (opacity: .8, filter: brightness()) erode the 40% contrast the decoder needs.
• Transparent backgrounds inherit the page colour: fine until dark mode flips it, the failure explored in QR codes on dark-mode websites.

Embedding patterns with markup samples live in embedding a QR code in HTML; when in doubt, screenshot the rendered page and run it through the validator.

FAQ

Can a QR code be rectangular?

The QR format itself is always square. Decoders tolerate slight stretching because it resembles an angled view, but it costs scanning margin. For genuinely rectangular slots the correct format is rMQR, a rectangular relative of the QR code.

How much padding does a QR code need?

At least 4 modules of clear background on all four sides, the quiet zone. As a version-independent rule, pad 20% of the code's width per side. The padding must scale with the rendered size, never be fixed in pixels.

Why does object-fit cover break QR codes?

Cover scales the image to fill the box and crops the overflow. On a QR code the cropped strip is the quiet zone and the outer modules, so scanners either fail to locate the code or misread its edge.

Should QR code padding be white?

It should match the code's light background colour, and be explicit rather than transparent. The decoder needs the quiet zone to contrast with the dark modules exactly as the background inside the code does.