Experimental responsive images

Ta treść nie jest jeszcze dostępna w Twoim języku.

Type: boolean
Default: false

Dodane w: astro@5.0.0

Enables support for automatic responsive images in your project.

{
  experimental: {
    responsiveImages: true,
  },
}

With this flag enabled, you have access to additional image configuration settings for controlling the default behavior of all images processed and optimized by Astro:

Local and remote images using the Markdown ![]() syntax.
The <Image /> and <Picture /> components.

Additionally, Astro’s image components can receive responsive image props to override these defaults on a per-image basis.

Images in your public/ folder are never optimized, and responsive images are not supported.

Responsive image configuration settings

Set image.experimentalLayout with a default value (responsive, fixed, or full-width) to enable responsive images throughout your project.

If this value is not configured, you can still pass a layout prop to any <Image /> or <Picture /> component to create a responsive image. However, Markdown images will not be responsive.

Optionally, you can configure image.experimentalObjectFit and image.experimentalObjectPosition which will apply to all processed images by default.

Each of these settings can be overridden on any individual <Image /> or <Picture /> component with a prop, but all Markdown images will always use the default settings.

{
  image: {
    // Used for all Markdown images; not configurable per-image
    // Used for all `<Image />` and `<Picture />` components unless overridden with a prop
    experimentalLayout: 'responsive',
  },
  experimental: {
    responsiveImages: true,
  },
}

Responsive image properties

These are additional properties available to the <Image /> and <Picture /> components when responsive images are enabled:

layout: The layout type for the image. Can be responsive, fixed, full-width, or none. Defaults to the value of image.experimentalLayout.
fit: Defines how the image should be cropped if the aspect ratio is changed. Values match those of CSS object-fit. Defaults to cover, or the value of image.experimentalObjectFit if set.
position: Defines the position of the image crop if the aspect ratio is changed. Values match those of CSS object-position. Defaults to center, or the value of image.experimentalObjectPosition if set.
priority: If set, eagerly loads the image. Otherwise, images will be lazy-loaded. Use this for your largest above-the-fold image. Defaults to false.

The widths and sizes attributes are automatically generated based on the image’s dimensions and the layout type, and in most cases should not be set manually. The generated sizes attribute for responsive and full-width images is based on the assumption that the image is displayed at close to the full width of the screen when the viewport is smaller than the image’s width. If it is significantly different (e.g. if it’s in a multi-column layout on small screens) you may need to adjust the sizes attribute manually for best results.

The densities attribute is not compatible with responsive images and will be ignored if set.

For example, with responsive set as the default layout, you can override any individual image’s layout property:

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="This will use responsive layout" width={800} height={600} />
<Image src={myImage} alt="This will use full-width layout" layout="full-width" />
<Image src={myImage} alt="This will disable responsive images" layout="none" />

Generated HTML output for responsive images

When a layout is set, either by default or on an individual component, images have automatically generated srcset and sizes attributes based on the image’s dimensions and the layout type. Images with responsive and full-width layouts will have styles applied to ensure they resize according to their container.

---
import { Image, Picture } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="A description of my image." layout='responsive' width={800} height={600} />
<Picture src={myImage} alt="A description of my image." layout='full-width' formats={['avif', 'webp', 'jpeg']} />

This <Image /> component will generate the following HTML output:

<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="A description of my image"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--w: 800; --h: 600; --fit: cover; --pos: center;"
  data-astro-image="responsive"
>

The following styles are applied to ensure the images resize correctly:

[data-astro-image] {
  width: 100%;
  height: auto;
  object-fit: var(--fit);
  object-position: var(--pos);
  aspect-ratio: var(--w) / var(--h)
}

[data-astro-image=responsive] {
  max-width: calc(var(--w) * 1px);
  max-height: calc(var(--h) * 1px)
}

[data-astro-image=fixed] {
  width: calc(var(--w) * 1px);
  height: calc(var(--h) * 1px)
}

For a complete overview, and to give feedback on this experimental API, see the Responsive Images RFC.

Pomóż nam Społeczność Sponsor