Custom QR code eye shapes — what survives detection

What an eye is, structurally

Each of the three corner eyes is a finder pattern: a 7 × 7 module structure — a dark ring one module thick around a light ring around a solid 3 × 3 dark ball. A scanner locates the code by sweeping scanlines for the signature proportions 1:1:3:1:1 (dark-light-dark-light-dark) that this structure produces in any direction through its centre. Detection happens before decoding, so error correction cannot compensate for a broken eye — the code is simply never found.

That gives styling a precise constraint: an eye variant is safe exactly in so far as it keeps three concentric shapes, solid ink, and the ratio along lines through the centre.

The five variants and their risk order

UseQR exposes eye styling as URL parameters — eye= for the outer frame, ball= for the centre — with five shapes each:

Style	Geometry	Ratio through centre	Risk
square	spec shape	exact everywhere	none
rounded	frame radius 2.2 × module, ball 0.9	exact on centre lines	very low
circle	full circles, ring one module thick	exact on any line through centre	low
leaf	rounded with one square corner	exact on centre lines, asymmetric off-centre	low–medium
diamond	rotated square	exact on axes, thins on diagonals	medium

Concentric circles preserve 1:1:3:1:1 along every line through their centre, which is why circle eyes are nearly as dependable as square. Leaf and diamond deviate more on off-centre scanlines and lose ink faster to blur at small print sizes — usable, but the variants to retest first when a styled code gets printed small.

Try a combination: rounded frames with circle balls.

The rules that outrank shape

• Solid ink only. No gradients fading the eyes, no patterns inside the ring, no fragmenting into dots — the ratio needs continuous dark runs.
• Contrast first. Eye colours (eyefg=, ballfg=) must pass the 40-point rule at least as strongly as the modules; the eyes should be the most readable part of the code, not the most decorated. When using gradients on modules, pin the eyes to the darkest stop.
• Never open the ring. A gap in the frame, a logo notching a corner, or a white outline effect breaks the dark run mid-scanline.
• The light ring is load-bearing. The one-module light gap between frame and ball is half the ratio; tinting it or letting the ball swell into it (UseQR's rounded ball radius stays at 0.9 × module for this reason) destroys the signature.

Corners can also differ from one another — the constraints per corner, and where a brand mark in an eye goes wrong, are covered in per-corner eye styling. Whatever combination you choose, decode the export with the validator: eye failures are binary and instant, so a verified code has, by definition, findable eyes.

FAQ

Can you change the shape of QR code eyes?

Yes. Rounded, circular, leaf and diamond eyes all scan when they remain solid, concentric, high-contrast structures preserving the 1:1:3:1:1 ratio through their centres. What breaks scanning is opening the ring, fading the ink, or filling the light gap.

Which QR eye shape is safest?

Square is the spec shape and carries zero risk; rounded is visually softer and effectively as safe. Circles are close behind because concentric circles keep the detection ratio along every line through the centre. Leaf and diamond work but merit retesting at small sizes.

Can the eyes be a different colour from the code?

Yes, and it can look sharp — but both frame and ball colours must keep at least a 40-point luminance difference against the background, with no gradients across the eye. The eyes should always be the highest-contrast element in the design.

Why does my code with styled eyes not scan?

Almost always a broken detection ratio: a fragmented or opened frame, a ball touching the frame, a tinted light ring, or eye colours too light. Restore solid concentric shapes and adequate contrast, then verify by decoding the artwork.