diff --git a/src/content/docs/en/guides/images.mdx b/src/content/docs/en/guides/images.mdx
index 976b26a22f436..91fbbbec33997 100644
--- a/src/content/docs/en/guides/images.mdx
+++ b/src/content/docs/en/guides/images.mdx
@@ -51,7 +51,7 @@ All native HTML tags, including ` ` and ``, are also available in `.ast
For all images in `.astro` files, **the value of the image `src` attribute is determined by the location of your image file**:
- A local image from your project `src/` folder uses an import from the file's relative path.
-
+
The image and picture components use the named import directly (e.g. `src={rocket}`), while the ` ` tag uses the `src` object property of the import (e.g. `src={rocket.src}`).
- Remote and `public/` images use a URL path.
@@ -321,7 +321,7 @@ import myImage from '../assets/my_image.png'; // Image is 1600x900
Responsive images are images that adjust to improve performance across different devices. These images can resize to fit their container, and can be served in different sizes depending on your visitor's screen size and resolution.
-With [responsive image properties](/en/reference/modules/astro-assets/#responsive-image-properties) applied to the ` ` or ` ` components, Astro will automatically generate the required `srcset` and `sizes` values for your images, and apply the necessary [styles to ensure they resize correctly](#responsive-image-styles).
+With the [layout property](/en/reference/modules/astro-assets/#layout) applied to the ` ` or ` ` components, Astro will automatically generate the required `srcset` and `sizes` values for your images, and apply the necessary [styles to ensure they resize correctly](#responsive-image-styles).
When this responsive behavior is [configured globally with `image.layout`](/en/reference/configuration-reference/#imagelayout), it will apply to all image components and also to any local and remote images using [the Markdown `![]()` syntax](/en/guides/images/#images-in-markdown-files).
@@ -396,7 +396,7 @@ The global styles applied by Astro will depend on the layout type, and are desig
The styles use the [`:where()` pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/:where), which has a [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity) of 0, meaning that it is easy to override with your own styles. Any CSS selector will have a higher specificity than `:where()`, so you can easily override the styles by adding your own styles to target the image.
-You can override the `object-fit` and `object-position` styles on a per-image basis by setting the `fit` and `position` props on the ` ` or ` ` component.
+You can override the `object-fit` and `object-position` styles on a per-image basis by setting the `fit` and `position` props on the ` ` or ` ` component.
#### Responsive images with Tailwind 4
diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx
index c40cdb499c5c5..5af9547aa9200 100644
--- a/src/content/docs/en/guides/upgrade-to/v6.mdx
+++ b/src/content/docs/en/guides/upgrade-to/v6.mdx
@@ -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?
@@ -715,6 +715,39 @@ If you need more control over environment variables in Astro, we recommend you u
Learn more about [environment variables](/en/guides/environment-variables/) in Astro, including `astro:env`.
+### Changed: Cropping by default in default image service
+
+
+
+In Astro 5.0, the default image service would only apply cropping when the `fit` option was provided.
+
+Astro 6.0 applies cropping by default without requiring setting the `fit` option.
+
+#### What should I do?
+
+No changes are needed to your existing cropped images as the `fit` property is still valid. However, if you were previously setting `fit` to `contain` (its default value) in order to crop your images, you may now remove this option and still achieve the same cropping behavior by specifying `width` and `height` alone:
+
+```ts title="src/components/MyImage.astro" del={5} ins={6}
+---
+import { Image } from 'astro:assets';
+import myImage from '../assets/photo.jpg';
+---
+
+
+```
+
+### Changed: Never upscale images in default image service
+
+
+
+In Astro 5.0, the default image service would upscale images when the requested dimensions were larger than the source image.
+
+Astro 6.0 removes this behavior: the default image service never upscales images.
+
+#### What should I do?
+
+Review your images and update dimensions as needed. 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
@@ -792,7 +825,7 @@ If you want to keep the old ID generation for backward compatibility reasons, yo
```
-
+
2. Create a custom rehype plugin that will generate headings IDs like Astro v5:
```js title="plugins/rehype-slug.mjs"
@@ -820,13 +853,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],
diff --git a/src/content/docs/en/reference/modules/astro-assets.mdx b/src/content/docs/en/reference/modules/astro-assets.mdx
index 376e3964171a9..71b6c9f914b07 100644
--- a/src/content/docs/en/reference/modules/astro-assets.mdx
+++ b/src/content/docs/en/reference/modules/astro-assets.mdx
@@ -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,
@@ -29,7 +29,6 @@ import {
The ` ` 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"
---
@@ -57,7 +56,7 @@ import myImage from "../assets/my_image.png"; // Image is 1600x900
#### Image properties
-The ` ` component accepts the following listed properties and [responsive image properties](#responsive-image-properties) in addition to all properties accepted by the HTML ` ` tag.
+The ` ` component accepts the following listed properties in addition to all properties accepted by the HTML ` ` tag.
##### src (required)
@@ -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 ` ` tag. Do not provide a value for `widths` when using this value.
@@ -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 ` ` 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`.
@@ -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.
@@ -322,13 +321,126 @@ fetchpriority="high"
These individual attributes can still be set manually if you need to customize them further.
+##### layout
+
+
+
+**Type:** `'constrained' | 'full-width' | 'fixed' | 'none'`
+**Default:** `image.layout | 'none'`
+
+
+
+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
+---
+import { Image } from 'astro:assets';
+import myImage from '../assets/my_image.png';
+---
+
+```
+
+When a layout is set, `srcset` and `sizes` attributes are automatically generated based on the image's dimensions and the layout type. The previous ` ` component will generate the following HTML output:
+
+```html
+
+```
+
+`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.
+
+ Use this if you want the image to display at the requested size where possible, but shrink to fit smaller screens. This matches the default behavior for images when using Tailwind. If you're not sure, this is probably the layout you should choose.
+
+- `full-width` - The image will scale to fit the width of the container, maintaining its aspect ratio.
+
+ Use this for hero images or other images that should take up the full width of the page.
+
+- `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.
+
+- `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.
+
+For example, with `constrained` set as the default layout, you can override any individual image's `layout` property:
+
+```astro title="src/components/MyComponent.astro"
+---
+import { Image } from 'astro:assets';
+import myImage from '../assets/my_image.png';
+---
+
+
+
+```
+
+The value for `layout` also defines the default styles applied to the ` ` tag to determine how the image should resize according to its container:
+
+```css title="Responsive Image Styles"
+:where([data-astro-image]) {
+ object-fit: var(--fit);
+ object-position: var(--pos);
+}
+:where([data-astro-image='full-width']) {
+ width: 100%;
+}
+:where([data-astro-image='constrained']) {
+ max-width: 100%;
+}
+```
+
+##### fit
+
+
+
+**Type:** `'contain' | 'cover' | 'fill' | 'none' | 'scale-down'`
+**Default:** `image.objectFit | 'cover'`
+
+
+
+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.
+
+##### position
+
+
+
+**Type:** `string`
+**Default:** `image.objectPosition | 'center'`
+
+
+
+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.
+
### ` `
The ` ` 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"
---
@@ -358,7 +470,7 @@ import myImage from "../assets/my_image.png"; // Image is 1600x900
#### Picture properties
-` ` accepts all the properties of [the ` ` component](#image-properties), including [responsive image properties](#responsive-image-properties), plus the following:
+` ` accepts all the properties of [the ` ` component](#image-properties) plus the following:
##### `formats`
@@ -385,7 +497,7 @@ Format to use as a fallback value for the ` ` tag. Defaults to `.png` for st
**Type:** `HTMLAttributes<'picture'>`
-An object of attributes to be added to the `` tag.
+An object of attributes to be added to the `` tag.
Use this property to apply attributes to the outer `` element itself. Attributes applied to the ` ` component directly will apply to the inner ` ` element, except for those used for image transformation.
@@ -417,123 +529,6 @@ import myImage from "../my_image.png"; // Image is 1600x900
```
-### Responsive image properties
-
-Setting the [`layout`](#layout) property on an [` `](#image-) or [` `](#picture-) component creates a responsive image and enables additional property settings.
-
-```astro title=MyComponent.astro
----
-import { Image } from 'astro:assets';
-import myImage from '../assets/my_image.png';
----
-
-```
-
- When a layout is set, `srcset` and `sizes` attributes are automatically generated based on the image's dimensions and the layout type. The previous ` ` component will generate the following HTML output:
-
-```html
-
-```
-The value for `layout` also defines the default styles applied to the ` ` tag to determine how the image should resize according to its container:
-
-```css title="Responsive Image Styles"
-:where([data-astro-image]) {
- object-fit: var(--fit);
- object-position: var(--pos);
-}
-:where([data-astro-image='full-width']) {
- width: 100%;
-}
-:where([data-astro-image='constrained']) {
- max-width: 100%;
-}
-```
-
-You can override the default `object-fit` and `object-position` styles by setting the [`fit`](#fit) and [`position`](#position) props on the ` ` or ` ` component.
-
-
-##### layout
-
-
-
-**Type:** `'constrained' | 'full-width' | 'fixed' | 'none'`
-**Default:** `image.layout | 'none'`
-
-
-
-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).
-
-- `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.
-
- Use this if you want the image to display at the requested size where possible, but shrink to fit smaller screens. This matches the default behavior for images when using Tailwind. If you're not sure, this is probably the layout you should choose.
-
-- `full-width` - The image will scale to fit the width of the container, maintaining its aspect ratio.
-
- Use this for hero images or other images that should take up the full width of the page.
-
-- `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.
-
-- `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.
-
-For example, with `constrained` set as the default layout, you can override any individual image's `layout` property:
-
-```astro title="src/components/MyComponent.astro"
----
-import { Image } from 'astro:assets';
-import myImage from '../assets/my_image.png';
----
-
-
-
-```
-
-##### fit
-
-
-
-**Type:** `'contain' | 'cover' | 'fill' | 'none' | 'scale-down'`
-**Default:** `image.objectFit | 'cover'`
-
-
-
-Enabled when the [`layout`](#layout) property is set or configured. Defines how a responsive 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.
-
-##### position
-
-
-
-**Type:** `string`
-**Default:** `image.objectPosition | 'center'`
-
-
-
-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.
-
-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()`