# Blurst

> A React image lightbox that opens on the first frame. It shows the thumbnail
> the browser has already cached, blurred, then swaps in the full-resolution
> image once it has decoded. Pinch to zoom, swipe to dismiss, gallery
> navigation, keyboard control. 7 kB gzipped, zero dependencies, no CSS import.

- Install: `npm i blurst`
- npm: https://www.npmjs.com/package/blurst
- Source: https://github.com/camc8/blurst
- Demo and API reference: https://blurst.vercel.app
- License: MIT
- Author: Cameron Clark (https://camc8.com)
- Requires: React 18 or 19. Works in the Next.js App Router (the package ships
  its own "use client" boundary).

## Exports

- `BlurstImage` — a drop-in `<img>` that opens in the lightbox on click. Props:
  `src` (rendered and used as the blurred placeholder), `full` (optional
  full-resolution source), `alt`, `caption`, `options`, plus every `<img>` prop.
- `Blurst` — wraps any single element (card, button, CSS background,
  `next/image`) and makes it the trigger. Props: `src`, `thumb`, `alt`,
  `caption`, `options`.
- `BlurstGroup` — turns the triggers inside it into one gallery, ordered by
  their position in the document.
- `BlurstProvider` — app-wide option defaults, and enables `useBlurst()`.
- `BlurstAuto` — attaches to images already in the DOM by CSS selector, without
  changing their markup. Props: `selector` (default `img[data-blurst]`), `root`,
  `gallery`, `options`.
- `useBlurst()` — imperative `{ open, close, isOpen }`; `open({ items, index,
  origin })`.
- `preloadImage`, `largestFromSrcset`, `defaultResolveFull`, `defaults`.

## How the full-resolution source is resolved

In order: the `full` prop, a `data-blurst` / `data-blurst-full` attribute, an
enclosing `<a>` whose href is an image, the largest candidate in `srcset`, then
the image's own `currentSrc` (in which case the lightbox opens sharp with no
second request).

## Options (defaults)

transition "zoom" · openDuration 260 · closeDuration 200 · blur 16 ·
backdrop "rgba(0,0,0,0.92)" · backdropBlur 0 · padding 24 · preload "hover" ·
swipeToDismiss true · swipeAxis "any" · dismissThreshold 96 · pinchToZoom true ·
doubleTapToZoom true · wheelToZoom true · maxScale 5 · doubleTapScale 2.5 ·
swipeToNavigate true · loop true · closeOnBackdropClick true · keyboard true ·
closeButton true · counter true · captions true · zIndex 9999 ·
container document.body · ariaLabel "Image viewer" · callbacks onOpen, onClose,
onIndexChange, onZoom.

Options merge from the nearest source outward: per trigger, then per group, then
`BlurstProvider`, then the built-in defaults.

## Minimal example

```tsx
import { BlurstImage } from "blurst";

<BlurstImage src="/photo-thumb.jpg" full="/photo-full.jpg" alt="Lysefjord" />;
```