+
+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
+
+
+
+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.
+
### ``
@@ -385,7 +411,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.
@@ -419,7 +445,7 @@ 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.
+Setting the [`layout`](#layout) property on an [``](#image-) or [``](#picture-) component creates a responsive image.
```astro title=MyComponent.astro
---
@@ -429,7 +455,7 @@ 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:
+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
` ta
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
@@ -491,11 +516,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:
@@ -509,32 +534,6 @@ import myImage from '../assets/my_image.png';
```
-##### fit
-
-
-
-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
-
-
-
-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()`
From e80dde9d6430d6da7c7e7fe80c0470c01dd53415 Mon Sep 17 00:00:00 2001
From: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
Date: Tue, 4 Nov 2025 15:40:58 +0100
Subject: [PATCH 2/8] fix: adapt for feedback
---
.../en/reference/modules/astro-assets.mdx | 179 +++++++++---------
1 file changed, 88 insertions(+), 91 deletions(-)
diff --git a/src/content/docs/en/reference/modules/astro-assets.mdx b/src/content/docs/en/reference/modules/astro-assets.mdx
index 297800eb40a7f..6bfd107dca13e 100644
--- a/src/content/docs/en/reference/modules/astro-assets.mdx
+++ b/src/content/docs/en/reference/modules/astro-assets.mdx
@@ -322,6 +322,93 @@ fetchpriority="high"
These individual attributes can still be set manually if you need to customize them further.
+##### layout
+
+
+
+Defines a responsive image 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).
+
+```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%;
+}
+```
+
+`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';
+---
+
+
+
+```
+
##### fit
@@ -384,7 +471,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`
@@ -443,96 +530,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.
-
-```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
-
-
-
-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';
----
-
-
-
-```
### `getImage()`
From 5eb5d4d45f22ba931a383150d23976bb91f9291d Mon Sep 17 00:00:00 2001
From: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
Date: Tue, 4 Nov 2025 17:02:10 +0100
Subject: [PATCH 3/8] fix: adjust for feedback
---
src/content/docs/en/guides/upgrade-to/v6.mdx | 37 +++++++++++++++++--
.../en/reference/modules/astro-assets.mdx | 14 +++----
2 files changed, 39 insertions(+), 12 deletions(-)
diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx
index c40cdb499c5c5..addcf317c2b08 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,35 @@ 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
+
+
+
+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';
+---
+
+
+```
+
+### Changed: Never upscale images in default image service
+
+
+
+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
@@ -792,7 +821,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 +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],
diff --git a/src/content/docs/en/reference/modules/astro-assets.mdx b/src/content/docs/en/reference/modules/astro-assets.mdx
index 6bfd107dca13e..1eaaca07d43f2 100644
--- a/src/content/docs/en/reference/modules/astro-assets.mdx
+++ b/src/content/docs/en/reference/modules/astro-assets.mdx
@@ -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.
@@ -418,7 +417,7 @@ import myImage from '../assets/my_image.png';
-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.
@@ -431,7 +430,7 @@ Values match those of CSS `object-fit`. Defaults to `cover`, or the value of [`i
-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.
@@ -441,7 +440,6 @@ Values match those of CSS `object-position`. Defaults to `center`, or the value
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"
---
From d5c3b1671bb7be93720238f064b6d62c965f9ecb Mon Sep 17 00:00:00 2001
From: Erika <3019731+Princesseuh@users.noreply.github.com>
Date: Tue, 4 Nov 2025 17:02:23 +0100
Subject: [PATCH 4/8] Update
src/content/docs/en/reference/modules/astro-assets.mdx
Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
---
src/content/docs/en/reference/modules/astro-assets.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/content/docs/en/reference/modules/astro-assets.mdx b/src/content/docs/en/reference/modules/astro-assets.mdx
index 1eaaca07d43f2..6070d55af8c22 100644
--- a/src/content/docs/en/reference/modules/astro-assets.mdx
+++ b/src/content/docs/en/reference/modules/astro-assets.mdx
@@ -330,7 +330,7 @@ These individual attributes can still be set manually if you need to customize t
-Defines a responsive image 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).
+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
---
From 5b9b9e8ba7d4915a583a951b20e453868ad4b501 Mon Sep 17 00:00:00 2001
From: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
Date: Tue, 4 Nov 2025 19:31:08 +0100
Subject: [PATCH 5/8] fix: update guide
---
src/content/docs/en/guides/images.mdx | 6 ++--
.../en/reference/modules/astro-assets.mdx | 31 ++++++++++---------
2 files changed, 20 insertions(+), 17 deletions(-)
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 `
+```
+The value for `layout` also defines the default styles applied to the `