Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
11 changes: 11 additions & 0 deletions src/content/docs/en/reference/configuration-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

<p>

**Type:** `boolean`<br />
**Default:** `true`
</p>

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


Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -146,9 +146,9 @@ This `<Image />` 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]) {
Expand All @@ -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 `<Image />` or `<Picture />` 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 `<Image />` or `<Picture />` 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).