diff --git a/src/content/docs/en/reference/configuration-reference.mdx b/src/content/docs/en/reference/configuration-reference.mdx index 5ebd628c57a5a..70098480f890d 100644 --- a/src/content/docs/en/reference/configuration-reference.mdx +++ b/src/content/docs/en/reference/configuration-reference.mdx @@ -1181,6 +1181,17 @@ The breakpoints used to generate responsive images. Requires the `experimental.r but is filtered according to the source and output size. The defaults used depend on whether a local or remote image service is used. For remote services the more comprehensive list is used, because only the required sizes are generated. For local services, the list is shorter to reduce the number of images generated. +### image.experimentalDefaultStyles + +

+ +**Type:** `boolean`
+**Default:** `true` +

+ +Whether to automatically add global styles to ensure that experimental images resize correctly. This is enabled by default, but can be disabled if you want to manage the styles yourself. +This option is only used when the `experimental.responsiveImages` flag is enabled. + ## Markdown Options diff --git a/src/content/docs/en/reference/experimental-flags/responsive-images.mdx b/src/content/docs/en/reference/experimental-flags/responsive-images.mdx index f6173b6a97784..1aefa7a9b4851 100644 --- a/src/content/docs/en/reference/experimental-flags/responsive-images.mdx +++ b/src/content/docs/en/reference/experimental-flags/responsive-images.mdx @@ -146,9 +146,9 @@ This `` component will generate the following HTML output: > ``` -## Overriding image styles +## Default responsive image styles -The responsive image component applies a small number of styles to ensure they resize correctly. The applied styles depend on the layout type, and are designed to give the best behavior for the generated `srcset` and `sizes` attributes. These are the default styles: +The responsive image component applies a small number of styles to ensure they resize correctly. The applied styles depend on the layout type, and are designed to give the best behavior for the generated `srcset` and `sizes` attributes: ```css title="Responsive Image Styles" :where([data-astro-image]) { @@ -163,10 +163,16 @@ The responsive image component applies a small number of styles to ensure they r } ``` -You can override the `object-fit` and `object-position` styles by setting the `fit` and `position` props on the `` or `` component. +### Overriding default styles -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 class or tag name will have a higher specificity than `:where()`, so you can easily override the styles by adding your own class or tag name to the image. +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. -Tailwind 4 is a special case, because it uses [cascade layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer), meaning the Tailwind rules are always lower specificity than rules that don't use layers. Astro supports browsers that do not support cascade layers, so it cannot use them for images. This means that if you need to override the styles using Tailwind 4, you must use [the `!important` modifier](https://tailwindcss.com/docs/styling-with-utility-classes#using-the-important-modifier). +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 disable the default styles entirely by setting [`image.experimentalDefaultStyles`](/en/reference/configuration-reference/#imageexperimentaldefaultstyles) to `false` if you prefer to handle styling responsive images yourself. + +#### Tailwind 4 + +Tailwind 4 is a special case, because it uses [cascade layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer), meaning the Tailwind rules are always lower specificity than rules that don't use layers. Astro supports browsers that do not support cascade layers, so it cannot use them for images. This means that [you should disable the default styles](/en/reference/configuration-reference/#imageexperimentaldefaultstyles) if you need to override them with Tailwind 4. 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).