mirror of
https://github.com/withastro/astro.git
synced 2024-12-16 21:46:22 -05:00
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
---
|
|
'astro': minor
|
|
---
|
|
|
|
Adds experimental support for automatic responsive images
|
|
|
|
This feature is experimental and may change in future versions. To enable it, set `experimental.responsiveImages` to `true` in your `astro.config.mjs` file.
|
|
|
|
```js title=astro.config.mjs
|
|
{
|
|
experimental: {
|
|
responsiveImages: true,
|
|
},
|
|
}
|
|
```
|
|
|
|
When this flag is enabled, you can pass a `layout` prop to any `<Image />` or `<Picture />` component to create a responsive image. When a layout is set, 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.
|
|
|
|
```astro
|
|
---
|
|
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:
|
|
```html title=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"
|
|
>
|
|
```
|
|
|
|
#### 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 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`.
|
|
|
|
#### Default responsive image settings
|
|
|
|
You can enable responsive images for all `<Image />` and `<Picture />` components by setting `image.experimentalLayout` with a default value. This can be overridden by the `layout` prop on each component.
|
|
|
|
**Example:**
|
|
```js title=astro.config.mjs
|
|
{
|
|
image: {
|
|
// Used for all `<Image />` and `<Picture />` components unless overridden
|
|
experimentalLayout: 'responsive',
|
|
},
|
|
experimental: {
|
|
responsiveImages: true,
|
|
},
|
|
}
|
|
```
|
|
|
|
```astro
|
|
---
|
|
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" />
|
|
```
|
|
|
|
For a complete overview, and to give feedback on this experimental API, see the [Responsive Images RFC](https://github.com/withastro/roadmap/blob/responsive-images/proposals/0053-responsive-images.md).
|