Pattern reference
Use this when you're choosing moduleShape, finderOuterShape or finderInnerShape by hand. Visual previews live in /examples.
Module shape — what the data cells look like
| Value | Coverage | Safe for printing? | Notes |
|---|---|---|---|
square | 100% | yes | The default. Safe everywhere. |
roundedsquare | ~95% | yes | Aesthetic upgrade with zero scan penalty. |
circle | ~78% | yes | Set moduleScale ≥ 0.85. |
dot | ~50% | yes — with ECC H | Lower coverage; engine raises ECC automatically. |
diamond | ~85% | yes | Looks great with roundedsquare finders. |
hexagon | ~90% | yes | Geometric, plays well with gradientDirection: diagonal. |
octagon | ~88% | yes | Similar to hexagon but flatter. |
cross | ~60% | yes — with ECC H | "Embroidered" look. |
star | ~55% | yes — with ECC H | Use moduleScale 0.9. |
heart | ~50% | yes — with ECC H | Decorative. Validate before printing. |
leaf | ~65% | yes — with ECC H | Organic. |
pointed, pointedinward, pointedsmooth | ~70% | yes | Sharp tips, modern feel. |
pill, roundedinward, roundedpointed | ~80% | yes | Smooth variations. |
mosaic | ~85% | yes | Looks like terracotta. |
japanese | ~75% | yes | Subtle texture. |
arrow, drop, shield, clipped, clippedsmooth, circlestripe | varies | depends on scale | Experimental — always test scan after export. |
Finder outer shape — the 3 corner frames
ISO 18004 only validates against rectangular finders, but most scanners are forgiving. The engine restricts you to shapes that decode reliably.
| Value | Notes |
|---|---|
square | Strict ISO. Use this if scanning under harsh conditions. |
roundedsquare | Same as square for scanners; softer for human eye. |
circle | Reliable. Pairs well with circle modules. |
diamond | Decode rate ~99.5%. Avoid for industrial scanners. |
octagon | Best non-square option. |
target | Concentric rings. Looks intentional. |
double | Two nested rectangles. Visual flourish. |
Finder inner shape — the "pupil"
| Value | Notes |
|---|---|
square | Default. |
roundedsquare | Subtle. |
circle | Most "branded" look. |
dot | Like circle but smaller — fits with dot modules. |
diamond | Geometric. |
star | Decorative only — use eccLevel: "H". |
How the AI picks
The AI never chooses heart, arrow or drop for production QRs unless you explicitly mention them in the prompt. It defaults to the safe quadrant: roundedsquare modules, roundedsquare or circle finders, ECC H. Anything outside that comes from the prompt or style: "artistic".
See also
- QrConfig reference — full param table
- /examples — visual gallery of every shape rendered
- Scan guarantee — what the engine checks before letting an export through