Skip to content

feat(reference): Update astro:assets reference for new Astro 6.0 behavior #12639

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
florian-lefebvre merged 8 commits into from
Nov 7, 2025
Merged

feat(reference): Update astro:assets reference for new Astro 6.0 behavior #12639

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2053bdd
feat(reference): Update astro:assets reference for new Astro 6.0 beha…
Princesseuh Oct 29, 2025
e80dde9
fix: adapt for feedback
Princesseuh Nov 4, 2025
5eb5d4d
fix: adjust for feedback
Princesseuh Nov 4, 2025
d5c3b16
Update src/content/docs/en/reference/modules/astro-assets.mdx
Princesseuh Nov 4, 2025
5b9b9e8
fix: update guide
Princesseuh Nov 4, 2025
e68803b
Apply suggestions from code review
Princesseuh Nov 5, 2025
35a13d9
Apply suggestions from code review
florian-lefebvre Nov 7, 2025
1cb765d
remove heading no longer needed
sarah11918 Nov 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 33 additions & 4 deletions src/content/docs/en/guides/upgrade-to/v6.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -375,7 +375,7 @@ You may also wish to consider using glob packages from NPM, such as [`fast-glob`

In Astro 5.0, accessing `routes` on the `astro:build:done` hook was deprecated.

Astro 6.0 removes the `routes` array passed to this hook entirely. Instead, the `astro:routes:resolved` hook should be used.
Astro 6.0 removes the `routes` array passed to this hook entirely. Instead, the `astro:routes:resolved` hook should be used.

#### What should I do?

Expand Down Expand Up @@ -715,6 +715,35 @@ If you need more control over environment variables in Astro, we recommend you u

<ReadMore>Learn more about [environment variables](/en/guides/environment-variables/) in Astro, including `astro:env`.</ReadMore>

### Changed: Cropping by default in default image service

<SourcePR number="14629" />

Astro's default image service now applies cropping by default without requiring setting the `fit` option.

#### What should I do?

Normally no changes are needed. However, if you were previously setting `fit` to `contain` (its default value) in order to crop, you may now remove this option to get the same behavior:

```ts title="src/components/MyImage.astro" del={4} ins={5}
---
import { Image } from 'astro:assets';
import myImage from '../assets/photo.jpg';
---
<Image src={myImage} width={400} height={300} fit="contain" />
<Image src={myImage} width={400} height={300} />
```

### Changed: Never upscale images in default image service

<SourcePR number="14629" />

In certain cases, Astro's default image service would upscale images when the requested dimensions were larger than the source image, which is often undesirable. This behavior has now been changed to never upscale images by default.

#### What should I do?

As upscaling images is typically undesirable, it is no longer possible to recreate the previous behavior in Astro itself. If you do need to upscale images, you may consider upscaling the images manually, or using a custom image service that supports upscaling.

### Changed: Markdown heading ID generation

<SourcePR number="14494" title="feat!: stabilize experimental.headingIdCompat"/>
Expand Down Expand Up @@ -792,7 +821,7 @@ If you want to keep the old ID generation for backward compatibility reasons, yo
```
</Fragment>
</PackageManagerTabs>

2. Create a custom rehype plugin that will generate headings IDs like Astro v5:

```js title="plugins/rehype-slug.mjs"
Expand Down Expand Up @@ -820,13 +849,13 @@ If you want to keep the old ID generation for backward compatibility reasons, yo
};
}
```

3. Add the custom plugin to your Markdown configuration in `astro.config.mjs`:

```js title="astro.config.mjs" ins={2} ins="rehypeSlug"
import { defineConfig } from 'astro/config';
import { rehypeSlug } from './plugins/rehype-slug';

export default defineConfig({
markdown: {
rehypePlugins: [rehypeSlug],
Expand Down
232 changes: 113 additions & 119 deletions src/content/docs/en/reference/modules/astro-assets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Astro provides built-in components and helper functions for optimizing and displ
## Imports from `astro:assets`

```js
import {
import {
Image,
Picture,
getImage,
Expand All @@ -29,7 +29,6 @@ import {

The `<Image />` component optimizes and transforms images.

This component can also be used to create [responsive images](#responsive-image-properties) that can adjust based on the size of their container or a device screen size and resolution.

```astro title="src/components/MyComponent.astro"
---
Expand Down Expand Up @@ -57,7 +56,7 @@ import myImage from "../assets/my_image.png"; // Image is 1600x900

#### Image properties

The `<Image />` component accepts the following listed properties and [responsive image properties](#responsive-image-properties) in addition to all properties accepted by the HTML `<img>` tag.
The `<Image />` component accepts the following listed properties in addition to all properties accepted by the HTML `<img>` tag.

##### src (required)

Expand Down Expand Up @@ -142,7 +141,7 @@ However, both of these properties are required for images stored in your `public

A list of pixel densities to generate for the image.

The `densities` attribute is not compatible with [responsive images](#responsive-image-properties) with a `layout` prop or `image.layout` config set, and will be ignored if set.
The `densities` attribute is not compatible with having the `layout` prop or `image.layout` config set, and will be ignored if set.

If provided, this value will be used to generate a `srcset` attribute on the `<img>` tag. Do not provide a value for `widths` when using this value.

Expand Down Expand Up @@ -189,7 +188,7 @@ A list of widths to generate for the image.

If provided, this value will be used to generate a `srcset` attribute on the `<img>` tag. A [`sizes` property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) must also be provided.

The `widths` and `sizes` attributes will be automatically generated for responsive images using a `layout` property. Providing these values is generally not needed, but can be used to override any automatically generated values.
The `widths` and `sizes` attributes will be automatically generated for images using a `layout` property. Providing these values is generally not needed, but can be used to override any automatically generated values.

Do not provide a value for `densities` when using this value. Only one of these two values can be used to generate a `srcset`.

Expand Down Expand Up @@ -242,7 +241,7 @@ import myImage from '../assets/my_image.png'; // Image is 1600x900

Specifies the layout width of the image for each of a list of media conditions. Must be provided when specifying `widths`.

The `widths` and `sizes` attributes will be automatically generated for responsive images using a `layout` property. Providing these values is generally not needed, but can be used to override any automatically generated values.
The `widths` and `sizes` attributes will be automatically generated for images using a `layout` property. Providing these values is generally not needed, but can be used to override any automatically generated values.

The generated `sizes` attribute for `constrained` and `full-width` images is based on the assumption that the image is displayed 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.

Expand Down Expand Up @@ -322,104 +321,16 @@ fetchpriority="high"

These individual attributes can still be set manually if you need to customize them further.

### `<Picture />`

<p><Since v="3.3.0" /></p>

The `<Picture />` component generates an optimized image with multiple formats and/or sizes.

This component can also be used to create [responsive images](#responsive-image-properties) that can adjust based on the size of their container or a device screen size and resolution.

```astro title="src/pages/index.astro"
---
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." />
```

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

#### Picture properties

`<Picture />` accepts all the properties of [the `<Image />` component](#image-properties), including [responsive image properties](#responsive-image-properties), plus the following:

##### `formats`

<p>

**Type:** `ImageOutputFormat[]`
</p>

An array of image formats to use for the `<source>` tags. Entries will be added as `<source>` elements in the order they are listed, and this order determines which format is displayed. For the best performance, list the most modern format first (e.g. `webp` or `avif`). By default, this is set to `['webp']`.

##### `fallbackFormat`

<p>

**Type:** `ImageOutputFormat`
</p>

Format to use as a fallback value for the `<img>` tag. Defaults to `.png` for static images (or `.jpg` if the image is a JPG), `.gif` for animated images, and `.svg` for SVG files.

##### `pictureAttributes`
##### layout

<p>

**Type:** `HTMLAttributes<'picture'>`
**Type:** `'constrained' | 'full-width' | 'fixed' | 'none'` <br />
**Default:** `image.layout | 'none'` <br />
<Since v="5.10.0" />
</p>

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.

```astro title="src/components/MyComponent.astro"
---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // Image is 1600x900
---

<Picture
src={myImage}
alt="A description of my image."
pictureAttributes={{ style: "background-color: red;" }}
/>
```

```html
<!-- Output -->
<picture style="background-color: red;">
<source srcset="/_astro/my_image.hash.webp" type="image/webp" />
<img
src="/_astro/my_image.hash.png"
alt="A description of my image."
width="1600"
height="900"
loading="lazy"
decoding="async"
/>
</picture>
```

### Responsive image properties

Setting the [`layout`](#layout) property on an [`<Image />`](#image-) or [`<Picture />`](#picture-) component creates a responsive image and enables additional property settings.
Determines how the image should resize when its container changes size. Can be used to override the default configured value for [`image.layout`](/en/reference/configuration-reference/#imagelayout).

```astro title=MyComponent.astro
---
Expand All @@ -429,7 +340,7 @@ import myImage from '../assets/my_image.png';
<Image src={myImage} alt="A description of my image." layout='constrained' width={800} height={600} />
```

When a layout is set, `srcset` and `sizes` attributes are automatically generated based on the image's dimensions and the layout type. The previous `<Image />` component will generate the following HTML output:
When a layout is set, `srcset` and `sizes` attributes are automatically generated based on the image's dimensions and the layout type. The previous `<Image />` component will generate the following HTML output:

```html
<img
Expand Down Expand Up @@ -467,19 +378,7 @@ The value for `layout` also defines the default styles applied to the `<img>` ta
}
```

You can override the default `object-fit` and `object-position` styles by setting the [`fit`](#fit) and [`position`](#position) props on the `<Image />` or `<Picture />` component.


##### layout

<p>

**Type:** `'constrained' | 'full-width' | 'fixed' | 'none'` <br />
**Default:** `image.layout | 'none'` <br />
<Since v="5.10.0" />
</p>

Defines a [responsive image](#responsive-image-properties) and determines how the image should resize when its container changes size. Can be used to override the default configured value for [`image.layout`](/en/reference/configuration-reference/#imagelayout).
`layout` supports the following values:

- `constrained` - The image will scale down to fit the container, maintaining its aspect ratio, but will not scale up beyond the specified `width` and `height`, or the image's original dimensions.

Expand All @@ -491,11 +390,11 @@ Defines a [responsive image](#responsive-image-properties) and determines how th

- `fixed` - The image will maintain the requested dimensions and not resize. It will generate a `srcset` to support high density displays, but not for different screen sizes.

Use this if the image will not resize, for example icons or logos smaller than any screen width, or other images in a fixed-width container.
Use this if the image will not resize, for example icons or logos smaller than any screen width, or other images in a fixed-width container.

- `none` - The image will not be responsive. No `srcset` or `sizes` will be automatically generated, and no styles will be applied.

This is useful if you have enabled a default layout, but want to disable it for a specific image.
This is useful if you have enabled a default layout, but want to disable it for a specific image.

For example, with `constrained` set as the default layout, you can override any individual image's `layout` property:

Expand All @@ -518,9 +417,9 @@ import myImage from '../assets/my_image.png';
<Since v="5.10.0" />
</p>

Enabled when the [`layout`](#layout) property is set or configured. Defines how a responsive image should be cropped if its aspect ratio is changed.
Defines how a image should be cropped if its aspect ratio is changed.

Values match those of CSS `object-fit`. Defaults to `cover`, or the value of [`image.objectFit`](/en/reference/configuration-reference/#imageobjectfit) if set. Can be used to override the default `object-fit` styles.
Values match those of CSS `object-fit`. Defaults to `cover`, or the value of [`image.objectFit`](/en/reference/configuration-reference/#imageobjectfit) if set. Can be used to override the default `object-fit` styles.

##### position

Expand All @@ -531,9 +430,104 @@ Values match those of CSS `object-fit`. Defaults to `cover`, or the value of [`i
<Since v="5.10.0" />
</p>

Enabled when the [`layout`](#layout) property is set or configured. Defines the position of the image crop for a responsive image if the aspect ratio is changed.
Defines the position of the image crop for a image if the aspect ratio is changed.

Values match those of CSS `object-position`. Defaults to `center`, or the value of [`image.objectPosition`](/en/reference/configuration-reference/#imageobjectposition) if set. Can be used to override the default `object-position` styles.

### `<Picture />`

<p><Since v="3.3.0" /></p>

The `<Picture />` component generates an optimized image with multiple formats and/or sizes.


```astro title="src/pages/index.astro"
---
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." />
```

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

#### Picture properties

`<Picture />` accepts all the properties of [the `<Image />` component](#image-properties) plus the following:

##### `formats`

<p>

**Type:** `ImageOutputFormat[]`
</p>

An array of image formats to use for the `<source>` tags. Entries will be added as `<source>` elements in the order they are listed, and this order determines which format is displayed. For the best performance, list the most modern format first (e.g. `webp` or `avif`). By default, this is set to `['webp']`.

##### `fallbackFormat`

<p>

**Type:** `ImageOutputFormat`
</p>

Format to use as a fallback value for the `<img>` tag. Defaults to `.png` for static images (or `.jpg` if the image is a JPG), `.gif` for animated images, and `.svg` for SVG files.

##### `pictureAttributes`

<p>

**Type:** `HTMLAttributes<'picture'>`
</p>

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.

```astro title="src/components/MyComponent.astro"
---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // Image is 1600x900
---

<Picture
src={myImage}
alt="A description of my image."
pictureAttributes={{ style: "background-color: red;" }}
/>
```

```html
<!-- Output -->
<picture style="background-color: red;">
<source srcset="/_astro/my_image.hash.webp" type="image/webp" />
<img
src="/_astro/my_image.hash.png"
alt="A description of my image."
width="1600"
height="900"
loading="lazy"
decoding="async"
/>
</picture>
```

Values match those of CSS `object-position`. Defaults to `center`, or the value of [`image.objectPosition`](/en/reference/configuration-reference/#imageobjectposition) if set. Can be used to override the default `object-position` styles.

### `getImage()`

Expand Down
Loading