# Blur-up image loading (`blur-up`)
A tiny blurred version of each photo (a 20 px JPEG, ~0.7 KB inlined) sits in a box of the right shape until the real photo has decoded, then the photo fades in. No grey boxes, no pop, no layout shift.
| | |
|---|---|
| Tag | Flow |
| Size | 1.1 KB gzipped own code (JS 0.7 KB + CSS 0.4 KB; 2.1 KB raw) |
| Dependency | none (vanilla + native APIs) |
| Best for | Every photo below the hero: galleries, work photos, team, review photos |
| Demo | `index.html` in this folder (live: https://wbl-code-lib.pages.dev/modules/blur-up/) |
## What it does
The figure carries the aspect ratio and the inline LQIP as its background (blurred by a pseudo-element, so the blur never touches the photo). The img starts at opacity 0 only when JS is on; JS waits for load + img.decode() before fading it in, so the fade never shows a half-painted image. Cached photos show instantly; a failed photo shows its alt text instead of a blur forever.
## When to use
- Any lazy-loaded photo. Make the LQIPs at build time (one line, below).
- Pair with Gallery lightbox and Photo review cards.
## Don't
- On the LCP hero: give it fetchpriority="high" and no fade (a fading LCP delays it).
- Placeholders bigger than ~1 KB each (20 px wide is plenty).
## Reduced motion, no JS, accessibility
- Reduced motion: the photo appears without the fade.
- No JS: photos load normally over the placeholder (they're never hidden).
- Alt text stays on the real img; the placeholder is a background (ignored by screen readers).
## Notes
- Make an LQIP with Pillow: im.thumbnail((20,20)); im.save(buf,'JPEG',quality=40) then base64 → data:image/jpeg;base64,… (see tools/resize.py). The builder's photo pipeline can emit it next to each photo.
## Relation to the effects libraries
New. (The batch 1 photos have -lqip.jpg files but no loader.)
## Use it
Copy this folder to the site as `/wbl/blur-up/` (keep `vendor/` if there is one), then:
```html
```
Colours come from CSS variables with safe defaults: `--wbl-accent`, `--wbl-on-accent`, `--wbl-ink`, `--wbl-paper`,
`--wbl-card`, `--wbl-line`, `--wbl-muted`, `--wbl-band`, `--wbl-radius`, `--wbl-head` (see the library README for the
one-line bridge to the preview builder's `--a / --ink / --bg …`).
## License
Our code: WBL-owned, original. No third-party code.
