astro-assets.mdx

title	i18nReady	tableOfContents
Assets API Reference	true	minHeadingLevel maxHeadingLevel 2 6

import Since from '/components/Since.astro'; import ReadMore from '/components/ReadMore.astro';

Astro provides built-in components and helper functions for optimizing and displaying your images. For features and usage examples, see our image guide.

Imports from astro:assets

import { 
  Image,
  Picture,
  getImage,
 } from 'astro:assets';

<Image />

---
// import the Image component and the image
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Image is 1600x900
---

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

<!-- Output -->
<!-- Image is optimized, proper attributes are enforced -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="A description of my image."
/>

Properties

• src (required)
• alt (required)
• width and height (required for public/ and remote images)
• format
• quality
• densities
• widths

In addition to the properties above, the <Image /> component accepts all properties accepted by the HTML <img> tag.

See more in the Images Guide.

<Picture />

Use the built-in <Picture /> Astro component to display a responsive image with multiple formats and/or sizes.

---
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 of my image." />

<!-- 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>

See more in the Images Guide.

Properties

<Picture /> accepts all the properties of the <Image /> component, plus the following:

formats

An array of image formats to use for the <source> tags. By default, this is set to ['webp'].

fallbackFormat

Format to use as a fallback value for the <img> tag. Defaults to .png for static images, .gif for animated images, and .svg for SVG files.

pictureAttributes

An object of attributes to be added to the <picture> tag. Use this property to apply attributes to the outer <picture> element itself. Attributes applied to the <Picture /> component directly will apply to the inner <img> element, except for those used for image transformation.

getImage()

Type: (options: UnresolvedImageTransform) => Promise<GetImageResult>

:::caution getImage() relies on server-only APIs and breaks the build when used on the client. :::

The getImage() function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an API Route. It also allows you to create your own custom <Image /> component.

getImage() takes an options object with the same properties as the Image component (except alt).

---
import { getImage } from "astro:assets";
import myBackground from "../background.png"

const optimizedBackground = await getImage({src: myBackground, format: 'avif'})
---

<div style={`background-image: url(${optimizedBackground.src});`}></div>

It returns an object with the following type:

type GetImageResult = {
  /* Additional HTML attributes needed to render the image (width, height, style, etc..) */
  attributes: Record<string, any>;
  /* Validated parameters passed */
  options: ImageTransform;
  /* Original parameters passed */
  rawOptions: ImageTransform;
  /* Path to the generated image */
  src: string;
  srcSet: {
    /* Generated values for srcset, every entry has a url and a size descriptor */
    values: SrcSetValue[];
    /* A value ready to use in`srcset` attribute */
    attribute: string;
  };
}