Automatically optimize your Astro images with the Unpic image service

Sun Jan 28 2024

Unpic has offered a native image component for Astro for nearly a year now, but I’m happy to announce that it now also offers an image service. This means you can get the benefit of Unpic’s responsive, high-performance images without changing any code in your site. Your existing Astro images will be automatically optimized - any that are hosted on a CDN that supports resizing will be resized there, and if you are deploying to Netlify or Vercel local images will automatically use those image CDNs. All other images will still work with the default Astro image service. You can carry on using the default Astro image component, and it will generate all the right sizes and srcset attributes for you. If you want more control you can still use the Unpic image component for Astro or any UI framework.

How does it work?

Let’s say you’re using Astro for your Contentful blog. Your data includes the URLs of your images, which are hosted on Contentful’s CDN. Here’s an example of displaying a list of blog posts:

import { Image } from "astro:assets";
import { contentfulClient } from "../lib/contentful";

const entries = await contentfulClient.getEntries({
  content_type: "blogPost",

{ => (

If you do this with the default Astro image component, it will generate something like this:


This has the right lazy loading props, but it isn’t responsive and uses the full-size image URL which is probably far too large.

We now enable Unpic by adding the service to astro.config.mjs:

import { defineConfig } from "astro/config";
import { imageService } from "@unpic/astro/service";
export default defineConfig({
  image: {
    service: imageService(),

Now we can look at the generated HTML again. The component itself is unchanged, but the generated HTML has been transformed to this:

  srcset=";fit=fill   640w,;fit=fill   750w,;fit=fill   828w,;fit=fill   960w,;fit=fill 1024w,;fit=fill 1080w,;fit=fill 1280w,;fit=fill 1668w,;fit=fill 1920w,;fit=fill 2048w
  sizes="(min-width: 1024px) 1024px, 100vw"

It has done this by recognizing that the image is hosted on Contentful’s CDN, and generating the correct URL for each size. It defaults to the “constrained” layout, though you can change this in the service config. The srcset and sizes attributes are generated based on this, and styles are added to ensure it resizes fluidly, avoids layout shift, and preserves aspect ratio.

Placeholder images

While an image is loading, it’s a good idea to show a placeholder. It avoids having a page full of white rectangles while the images load, and can reduce largest contentful paint times. Now on Astro, Unpic will automatically generate placeholder images for you. There are three types of placeholder that it can generate: dominant color, blurhash and low-res image. Have a look at the placeholder demo to see them in action.

Take a look at the docs for more details on how to use the new Astro image service.