Adding image placeholders
Limited compatibilityRendering:Prerendered: Recommended*On-demand: Doesn't work*Runtimes:Astro>=5.10.0
Local Sharp placeholders run during your build on Node.js. On-demand routes should use precomputed placeholders or a CDN-backed solution such as @unpic/astro.
- Prerendered: Generates placeholders once at build time with Sharp and embeds them directly into the static HTML.
- On-demand: Reading local source files from disk with Sharp is built for prerendered pages; for on-demand routes or remote images, precompute placeholders in your CMS or use an image CDN such as @unpic/astro.
- Cloudflare Workers: Native Sharp binaries cannot run inside Cloudflare Workers at request time; prerender routes with local placeholders during your Node.js build instead.
Even well-optimized WebP and AVIF images take a moment to arrive over a cellular connection. Without a placeholder, the visitor sees an empty patch of background where a photograph belongs, making a fast page feel half-finished.
Before reaching for a blur effect, though, it helps to separate two problems that often get lumped together:
- Layout shift (CLS) does not require a placeholder. Astro’s built-in
<Image />and<Picture />components already emit explicitwidthandheightattributes, and settinglayout="constrained"withimage.responsiveStyles: truekeeps responsive images locked to their aspect ratio before a single pixel downloads. - Perceived loading is what placeholders actually improve. A quiet visual cue tells the reader that media is on the way rather than leaving them wondering whether the layout broke.
The catch is that a badly implemented placeholder is worse than none at all. Turning a diagram or screenshot into an unrecognizable smudge creates visual noise and a jarring mental snap when the real graphic appears. Worse, hiding the real image URL in data-src and swapping it with a JavaScript lazy-loader blinds the browser’s preload scanner, delays Largest Contentful Paint (LCP), hurts image indexing, and strands visitors without JavaScript on a blurry rectangle forever.
This recipe avoids those traps. You will build a drop-in <PlaceholderImage /> wrapper around Astro’s <Image /> that generates a dominant color or a tiny blurred WebP at build time with Sharp and applies it as an inline CSS background. The real src and srcset stay right on the <img> element, opaque photos need zero client-side JavaScript, and every native Astro prop—including layout and priority—continues to work unchanged.
Choosing a placeholder style
Section titled “Choosing a placeholder style”Not every image benefits from the same treatment. Match the placeholder to the content and the number of images on the page:
| Style | Inline HTML cost | Visual feel | Best for |
|---|---|---|---|
| None | 0 B |
Clean reserved space | UI screenshots, charts, icons, and small thumbnails |
| Dominant color | ~20 B |
Calm, solid tint | Galleries, grids, and cards with many images per page |
| Blurred LQIP | ~350–600 B |
Soft preview of color and shape | Hero photos, article covers, and editorial photography |
Building <PlaceholderImage />
Section titled “Building <PlaceholderImage />”Astro already uses Sharp as its default local image service. If you use a strict package manager such as pnpm, add sharp as a direct dependency so your helper can import it cleanly:
-
Create a build-time placeholder helper.
This utility reads an imported image (from
src/or a Content Collectionimage()field) and returns inline CSS background properties for either"blur"or"dominantColor".src/lib/image-placeholder.ts import type { ImageMetadata } from "astro";import sharp from "sharp";export type PlaceholderType = "blur" | "dominantColor" | "none";type LocalImageMetadata = ImageMetadata & {fsPath?: string;};type PlaceholderStyle = Record<string, string>;const placeholderCache = new Map<string, Promise<PlaceholderStyle>>();async function generatePlaceholder(fsPath: string,type: Exclude<PlaceholderType, "none">,): Promise<PlaceholderStyle> {if (type === "dominantColor") {const { dominant } = await sharp(fsPath).stats();return {"background-color": `rgb(${dominant.r} ${dominant.g} ${dominant.b})`,};}const buffer = await sharp(fsPath).resize(20, 20, { fit: "inside", withoutEnlargement: true }).blur(1).webp({ quality: 20 }).toBuffer();const dataUri = `data:image/webp;base64,${buffer.toString("base64")}`;return {"background-image": `url("${dataUri}")`,"background-size": "cover","background-position": "center","background-repeat": "no-repeat",};}export async function getPlaceholderStyle(src: ImageMetadata,type: PlaceholderType = "blur",): Promise<PlaceholderStyle> {if (type === "none") {return {};}const fsPath = (src as LocalImageMetadata).fsPath;if (!fsPath) {return {};}const cacheKey = `${fsPath}:${type}`;let pending = placeholderCache.get(cacheKey);if (!pending) {pending = generatePlaceholder(fsPath, type);placeholderCache.set(cacheKey, pending);}return pending;}A few deliberate choices make this helper fast and dependable:
- Reading
fsPathdirectly: Astro attaches a non-enumerablefsPathproperty to localImageMetadataobjects during development and static builds. Reading the original file fromfsPathworks identically inastro devandastro build, avoids fragile./dist/path assumptions, and does not force Astro to copy the unoptimized source file into your output directory. - Blurring in Sharp instead of CSS: A 1-pixel Gaussian blur at
20 × 20smooths out compression artifacts before base64 encoding. Because the blur lives inside the tiny data URI, you do not need a CSSfilter: blur()or anoverflow: hiddenwrapper element around the<img>. - Caching the promise: Storing the in-flight
PromiseinplaceholderCacheensures that an image reused across dozens of pages or cards is decoded by Sharp only once per build.
- Reading
-
Create the
<PlaceholderImage />component.Wrap Astro’s
<Image />component so callers keep the fullLocalImagePropsAPI—responsivelayout,widths,sizes,priority,format,class, and customstyle—while gaining aplaceholderprop.src/components/PlaceholderImage.astro ---import { Image, type LocalImageProps } from "astro:assets";import {getPlaceholderStyle,type PlaceholderType,} from "~/lib/image-placeholder";type Props = LocalImageProps & {placeholder?: PlaceholderType;};const { placeholder = "blur", style, ...imageProps } = Astro.props;const resolvedSrc ="then" in imageProps.src ? (await imageProps.src).default : imageProps.src;const placeholderStyle = await getPlaceholderStyle(resolvedSrc, placeholder);const hasPlaceholder = Object.keys(placeholderStyle).length > 0;const mergedStyle = !hasPlaceholder? style: typeof style === "string"? `${Object.entries(placeholderStyle).map(([prop, val]) => `${prop}: ${val}`).join("; ")}; ${style}`: { ...placeholderStyle, ...style };---<Image{...imageProps}src={resolvedSrc}{...(mergedStyle != null ? { style: mergedStyle } : {})}/>Because the placeholder is rendered as a CSS background on the
<img>itself, opaque formats (JPEG, opaque WebP, AVIF, or flat PNG) cover the placeholder completely the instant they finish decoding—no wrapper<div>, no hydration, and no client script required. -
Use
<PlaceholderImage />in your pages.Use
"blur"selectively for hero photography and"dominantColor"(or"none") for denser lists or UI graphics.src/pages/index.astro ---import PlaceholderImage from "~/components/PlaceholderImage.astro";import heroPhoto from "~/assets/hero.jpg";import cardThumb from "~/assets/card.jpg";import diagram from "~/assets/architecture.png";---<!-- Above-the-fold hero: eager + high priority, blurred LQIP --><PlaceholderImagesrc={heroPhoto}alt="Sunlight over a mountain ridge at dawn"layout="full-width"priorityplaceholder="blur"/><!-- Grid card: tiny dominant-color fill to keep HTML lean --><PlaceholderImagesrc={cardThumb}alt="Coffee cup on a wooden desk"width={640}layout="constrained"placeholder="dominantColor"/><!-- Crisp technical graphic: skip the placeholder altogether --><PlaceholderImagesrc={diagram}alt="Request flow diagram"width={800}layout="constrained"placeholder="none"/>Notice how
prioritycomposes naturally with the placeholder: Astro emitsloading="eager",decoding="sync", andfetchpriority="high"on the hero<img>, so the real image starts downloading immediately while the inline background fills the frame during transfer.
Handling transparent images
Section titled “Handling transparent images”If an image has transparent pixels—such as a cut-out product shot or a transparent PNG logo—the CSS background will stay visible behind the transparent areas even after the image loads.
The simplest fix is to pass placeholder="none" for transparent assets. If you want placeholders on transparent images anyway, add a data-placeholder attribute to <Image /> and clear the background properties once the image finishes loading:
<Image {...imageProps} src={resolvedSrc} {...(mergedStyle != null ? { style: mergedStyle } : {})} {...(hasPlaceholder ? { "data-placeholder": "" } : {})}/>
<script> function clearPlaceholder(img: HTMLImageElement) { img.style.removeProperty("background-image"); img.style.removeProperty("background-color"); img.style.removeProperty("background-size"); img.style.removeProperty("background-position"); img.style.removeProperty("background-repeat"); img.removeAttribute("data-placeholder"); }
function initPlaceholders() { document .querySelectorAll<HTMLImageElement>("img[data-placeholder]") .forEach((img) => { if (img.dataset.placeholder === "bound") return; if (img.complete && img.naturalHeight > 0) { clearPlaceholder(img); return; } img.dataset.placeholder = "bound"; img.addEventListener("load", () => clearPlaceholder(img), { once: true }); }); }
initPlaceholders(); document.addEventListener("astro:page-load", initPlaceholders);</script>Two details here prevent subtle bugs that often sneak into image-loading scripts:
- Checking
img.complete && img.naturalHeight > 0: Images served from the browser cache often finish loading before a module script executes, meaning theloadevent has already fired. CheckingcompletealongsidenaturalHeight > 0(which excludes cached broken images) clears the background immediately instead of leaving it stuck behind a transparent asset. - Never hiding the
<img>with staticopacity: 0: Fade-in snippets that setopacity: 0in CSS and rely ononloadto reveal the image break completely when JavaScript is disabled and can delay LCP on hero images. Keeping the<img>visible from the start makes the script a pure progressive enhancement.
Listening to astro:page-load in addition to the initial call also ensures the cleanup runs smoothly after client-side navigations if your site uses <ClientRouter />.
Remote and CDN-hosted images
Section titled “Remote and CDN-hosted images”The Sharp helper above reads local files imported from src/. If your images live on a remote image CDN (such as Cloudinary, Imgix, Shopify, Unsplash, Netlify, or Vercel), @unpic/astro supports build-time placeholders for remote URLs out of the box—either through its <Image /> component or by registering @unpic/astro/service in astro.config.mjs:
import { defineConfig } from "astro/config";import { imageService } from "@unpic/astro/service";
export default defineConfig({ image: { service: imageService({ placeholder: "blurhash", // or "dominantColor" | "lqip" }), },});Unpic decodes BlurHash placeholders on the server into tiny inline CSS backgrounds, so they require no client-side JavaScript either. Keep in mind that @unpic/astro’s placeholder option only applies to remote images and is ignored for local imports—which makes it a clean complement to the local Sharp component in this recipe.
For on-demand rendered pages backed by a CMS or database (such as Sanity, Contentful, Directus, or Strapi), avoid running Sharp on every incoming request. Instead, generate a dominant color or placeholder hash once at upload time, store it alongside the image record, and pass it into your Astro component as an inline background-color or data URI.
Pitfalls to watch out for
Section titled “Pitfalls to watch out for”- HTML payload bloat on image-heavy pages: A single
20 × 20WebP LQIP adds roughly 350–600 bytes to your HTML. On an article with three photos, that is negligible; on a product grid with 60 thumbnails, it adds ~30 KB of uncacheable inline data to the initial document and pushes back First Contentful Paint. Switch dense grids toplaceholder="dominantColor"or"none". - Internal
fsPathis build-time only: Astro populatesfsPathwith the file path on the machine that runs the build. Use<PlaceholderImage />on prerendered pages (Astro’s default) and duringastro dev, not on deployed on-demand routes where source files are absent from disk or native Sharp binaries are unavailable. - Don’t blur text, charts, or UI: Photographs transition cleanly from a soft preview to crisp detail. Screenshots, diagrams, and typography turn into distracting blobs—reserve
"blur"for photography and use a solid color or plain reserved dimensions for everything else.
Full code
Section titled “Full code”import type { ImageMetadata } from "astro";import sharp from "sharp";
export type PlaceholderType = "blur" | "dominantColor" | "none";
type LocalImageMetadata = ImageMetadata & { fsPath?: string;};
type PlaceholderStyle = Record<string, string>;
const placeholderCache = new Map<string, Promise<PlaceholderStyle>>();
async function generatePlaceholder( fsPath: string, type: Exclude<PlaceholderType, "none">,): Promise<PlaceholderStyle> { if (type === "dominantColor") { const { dominant } = await sharp(fsPath).stats(); return { "background-color": `rgb(${dominant.r} ${dominant.g} ${dominant.b})`, }; }
const buffer = await sharp(fsPath) .resize(20, 20, { fit: "inside", withoutEnlargement: true }) .blur(1) .webp({ quality: 20 }) .toBuffer();
const dataUri = `data:image/webp;base64,${buffer.toString("base64")}`;
return { "background-image": `url("${dataUri}")`, "background-size": "cover", "background-position": "center", "background-repeat": "no-repeat", };}
export async function getPlaceholderStyle( src: ImageMetadata, type: PlaceholderType = "blur",): Promise<PlaceholderStyle> { if (type === "none") { return {}; }
const fsPath = (src as LocalImageMetadata).fsPath; if (!fsPath) { return {}; }
const cacheKey = `${fsPath}:${type}`; let pending = placeholderCache.get(cacheKey); if (!pending) { pending = generatePlaceholder(fsPath, type); placeholderCache.set(cacheKey, pending); }
return pending;}---import { Image, type LocalImageProps } from "astro:assets";import { getPlaceholderStyle, type PlaceholderType,} from "~/lib/image-placeholder";
type Props = LocalImageProps & { placeholder?: PlaceholderType;};
const { placeholder = "blur", style, ...imageProps } = Astro.props;
const resolvedSrc = "then" in imageProps.src ? (await imageProps.src).default : imageProps.src;const placeholderStyle = await getPlaceholderStyle(resolvedSrc, placeholder);const hasPlaceholder = Object.keys(placeholderStyle).length > 0;
const mergedStyle = !hasPlaceholder ? style : typeof style === "string" ? `${Object.entries(placeholderStyle) .map(([prop, val]) => `${prop}: ${val}`) .join("; ")}; ${style}` : { ...placeholderStyle, ...style };---
<Image {...imageProps} src={resolvedSrc} {...(mergedStyle != null ? { style: mergedStyle } : {})} {...(hasPlaceholder ? { "data-placeholder": "" } : {})}/>
<script> function clearPlaceholder(img: HTMLImageElement) { img.style.removeProperty("background-image"); img.style.removeProperty("background-color"); img.style.removeProperty("background-size"); img.style.removeProperty("background-position"); img.style.removeProperty("background-repeat"); img.removeAttribute("data-placeholder"); }
function initPlaceholders() { document .querySelectorAll<HTMLImageElement>("img[data-placeholder]") .forEach((img) => { if (img.dataset.placeholder === "bound") return; if (img.complete && img.naturalHeight > 0) { clearPlaceholder(img); return; } img.dataset.placeholder = "bound"; img.addEventListener("load", () => clearPlaceholder(img), { once: true }); }); }
initPlaceholders(); document.addEventListener("astro:page-load", initPlaceholders);</script>Compatibility
Local Sharp placeholders run during your build on Node.js. On-demand routes should use precomputed placeholders or a CDN-backed solution such as @unpic/astro.
| Environment | Support | Version |
|---|---|---|
| Framework | ||
| Astro | Works | >=5.10.0 |
| RenderingAstro docs | ||
| Prerendered | Recommended[1] | Any version |
| On-demand | Doesn't work[2] | Any version |
| Runtimes | ||
| Node.js | Recommended | Any version |
| Cloudflare Workers | Doesn't work[3] | Any version |
Notes
- Prerendered: Generates placeholders once at build time with Sharp and embeds them directly into the static HTML.
- On-demand: Reading local source files from disk with Sharp is built for prerendered pages; for on-demand routes or remote images, precompute placeholders in your CMS or use an image CDN such as @unpic/astro.
- Cloudflare Workers: Native Sharp binaries cannot run inside Cloudflare Workers at request time; prerender routes with local placeholders during your Node.js build instead.