Image

Drop-in <Image /> replacement with BlurHash placeholder and content-negotiated format.

<AuraImage /> is a Shadcn-registry component you copy into your project. It's a drop-in replacement for <img> that crossfades a BlurHash (or LQIP) placeholder into the full image, eliminating LCP jank.

Because it ships as source — not a binary dependency — you own the file and edit it freely.

Install

npx shadcn@latest add https://auraimage.ai/registry/image.json

This copies one file into src/components/aura/image.tsx. The component depends on blurhash (npm) for client-side hash decoding; shadcn installs it for you.

It reads your CDN base URL from NEXT_PUBLIC_AURA_CDN_URL (set during aura init).

Usage

import { AuraImage } from '@/components/aura/image';

export default function Hero() {
  return (
    <AuraImage
      src='my-app/abc123xyz0-hero.jpg'
      alt='Golden Gate Bridge at sunset'
      width={1200}
      height={800}
      priority
    />
  );
}

src is the full CDN path in projectName/filename form. The key returned by signUpload is exactly the filename part — combine it with your project name.

Props

Prop	Type	Default	Description
`src`	`string`	required	`projectName/filename`, e.g. `"my-app/abc123xyz0-hero.jpg"`.
`alt`	`string`	required	Alt text. Use the `generate_alt` MCP tool to backfill missing alts.
`width`	`number`	required	Display width in pixels.
`height`	`number`	required	Display height in pixels.
`priority`	`boolean`	`false`	Sets `loading="eager"` and `fetchpriority="high"`. Use for the largest above-the-fold image.
`placeholder`	`"blurhash" \| "lqip" \| "empty"`	`"blurhash"`	Placeholder strategy.
`quality`	`number`	`80`	Compression quality (1–100). Maps to the `q` URL param.
`fit`	`"cover" \| "contain" \| "face" \| "auto"`	`"cover"`	Crop / fit mode. Maps to the `fit` URL param.
`format`	`"auto" \| "avif" \| "webp" \| "jpeg"`	`"auto"`	Output format. Maps to the `fmt` URL param.
`className`	`string`	—	Extra classes merged onto the wrapping `<div>`.
`telemetry`	`boolean`	`false`	When set, reports the page's LCP timing back to AuraImage. Powers the dashboard's per-page LCP chart.

Placeholder strategies

Strategy	How it works	When to use
`blurhash` (default)	Fetches `GET /v1/blurhash/<projectName>/<filename>`, decodes the hash on the client, paints it into a canvas, crossfades into the full image. One small, cacheable request per image.	Default. Highest fidelity for the bandwidth.
`lqip`	Fetches a 50px-wide JPEG (`?lqip=true`) before the full image. One extra image request.	When you want a sharper, photographic placeholder.
`empty`	Renders nothing until the full image loads.	Small images, or when you have your own skeleton.

If placeholder="blurhash" is set and the blurhash fetch fails (network, malformed hash), the component automatically falls back to lqip — you always get a placeholder.

How it transforms URLs

<AuraImage /> builds the delivery URL from your props:

${NEXT_PUBLIC_AURA_CDN_URL}/${src}?w=${width}&h=${height}&q=${quality}&fmt=${format}&fit=${fit}

fmt=auto and fit=cover are omitted from the query string (server defaults). When src, width, format, or fit change, the component resets its loaded state so the new variant fades in fresh — no stale frame stays on screen during the swap.

See the URL API for the full param reference.

Install

Usage

Props

Placeholder strategies

How it transforms URLs

On this page