# Custom QR code eye shapes: what survives detection

> Eye shapes can be restyled as long as each finder pattern stays a solid concentric dark-light-dark structure preserving the 1:1:3:1:1 scanline ratio. Square and rounded are safest, circles preserve the ratio through their centres, and leaf and diamond carry slightly more risk at angles and small sizes.

Source: https://useqr.app/docs/design/custom-eye-shapes · Last reviewed 2026-08-21 · UseQR is free forever, no signup.

---

## What an eye is, structurally

Each of the three corner eyes is a [finder pattern](/glossary/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](/docs/spec/error-correction-levels-explained) 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](/docs/print/qr-code-size-for-print).

Try a combination: [rounded frames with circle balls](/url?eye=rounded&ball=circle).

## 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](/docs/design/qr-code-contrast-ratio-minimum) 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](/docs/design/gradient-qr-codes), 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](/docs/design/per-corner-eye-styling). Whatever combination
you choose, decode the export with the [validator](/validate): 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.

## Try it

- https://useqr.app/url
- https://useqr.app/validate