Astro JS - Images

---

---

Images in Astro

Images are important parts of modern websites. Astro provides multiple ways to handle images in your project. By default, images in Astro are highly optimized for performance and SEO. Astro provides a built-in image component that allows you to easily add optimized and responsive images to your site.

Image Storage in Astro

Images in Astro can be stores of either '/src' or '/public' directory. Let's see the difference.

• '/src' directory: The image files stored in '/src' directory are processed, transformed and optimized by Astro. The images will be available in any files of your project.
• '/public' directory: The images stored in '/public' directory are always served or copied into the build folder as it is, without any processing. This is only recommended when you want to avoid any processing or to have a direct public link to them.

Display Optimized Images

Astro uses a custom <Image> component which extents HTML <img> tag to optimize images in your project. The <Image> component automatically generates multiple sizes of an image and serves the most appropriate size based on the device's screen size. The resulting <img> tag includes alt, loading, and decoding attributes and infers image dimensions to avoid Cumulative Layout Shift (CLS). Let's see an example.

---
// import the Image component and the image
import { Image } from 'astro:assets';
import myImage from '../assets/logo.png';
---

<!-- `alt` is mandatory on the Image component -->
<Image src={myImage} alt="A description" />

Output

The output is shown below. You can see that the image is displayed in the browser.

Note: The <Image> component accepts several component properties as well as any attributes accepted by the HTML <img> tag.

Create Responsive Images

Astro uses a built-in <Picture> component to create responsive images. The <Picture> component allows you to define multiple sources for an image and serves the most appropriate image based on the device's screen size. Let's see an example.

---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image is 1600x900
---

<!-- `alt` is mandatory on the Picture component -->
<Picture src={myImage} formats={['avif', 'webp']} alt="A description" />

Output

Astro will convert the above code to following format in plain HTML.

<!-- Output -->
<picture>
    <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
    <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
    <img
        src="/_astro/my_image.hash.png"
        width="1600"
        height="900"
        decoding="async"
        loading="lazy"
        alt="A description of my image."
    />
</picture>

Remote Images

You can configure lists of authorized image source URL domains and patterns for image optimization using image.domains and image.remotePatterns. This configuration is an extra layer of safety to protect your site when showing images from an external source. Remote images from other sources will not be optimized, but using the <Image> component for these images will prevent Cumulative Layout Shift (CLS).

For example, the following configuration will only allow remote images from tutorialspoint.com to be optimized:

// astro.config.mjs

export default defineConfig({
    image: {
      domains: ["tutorialspoint"],
    }
  });

The following configuration will only allow remote images from HTTPS hosts:

// astro.config.mjs

export default defineConfig({
    image: {
        remotePatterns: [{ protocol: "https" }],
    }
  });

Images in Markdown files

To add images to markdown files, use standard Markdown  syntax in your .md files. This syntax works with Astro’s Image Service API to optimize your local images stored in src/ and remote images. Images stored in the public/ folder are never optimized.

Example

Here is an example of how to add different types of images to a markdown file.

# The Markdown Page

<!-- Local image stored in src/assets/ -->
<!-- Use a relative file path or import alias -->
![A starry night sky.](../assets/stars.png)

<!-- Image stored in public/images/ -->
<!-- Use the file path relative to public/ -->
![A starry night sky.](/images/stars.png)

<!-- Remote image on another server -->
<!-- Use the full URL of the image -->
![Astro](https://example.com/images/remote-image.png)