Skip to content

Add note on disabling default styles #11787

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
yanthomasdev merged 5 commits into from
May 30, 2025
Merged

Add note on disabling default styles #11787

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4541591
Add note on disabling default styles
ascorbic May 28, 2025
4186cd2
docgen
ascorbic May 28, 2025
adaccca
combine info on overriding, separate from disabling
sarah11918 May 28, 2025
6df1589
link and text corrections
sarah11918 May 28, 2025
e3f1aea
Merge branch 'main' into disable-image-styles
yanthomasdev May 30, 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
11 changes: 11 additions & 0 deletions src/content/docs/en/reference/configuration-reference.mdx
View file
Open in desktop
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.

### experimentalDefaultStyles
Comment thread
sarah11918 marked this conversation as resolved.
Outdated

<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
6 changes: 4 additions & 2 deletions src/content/docs/en/reference/experimental-flags/responsive-images.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,9 @@

## Overriding 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. You can override them with your own styles, or disable them entirely by setting [`image.experimentalDefaultStyles`](/en/reference/configuration-reference/#imageexperimentaldefaultstyles) to `false` if you prefer to handle styling them yourself.

Check failure on line 151 in src/content/docs/en/reference/experimental-flags/responsive-images.mdx

View workflow job for this annotation

GitHub Actions / Check Links 

Broken fragment link in src/content/docs/en/reference/experimental-flags/responsive-images.mdx, line 151: The linked page does not contain a fragment with the name "#imageexperimentaldefaultstyles". Available fragments: #theme-icons, #gradient, #starlight__sidebar, #__tab-start, #__tab-guides-and-recipes, #__tab-reference, #__tab-integrations, #__tab-third-party-services, #starlight__mobile-toc, #starlight__on-this-page--mobile, #starlight__on-this-page, #learn-astro-course-2, #_top, #top-level-options, #site, #base, #trailingslash, #redirects, #output, #adapter, #integrations, #root, #examples, #srcdir, #publicdir, #outdir, #cachedir, #compresshtml, #scopedstylestrategy, #security, #securitycheckorigin, #vite, #examples-1, #build-options, #buildformat, #effect-on-astrourl, #buildclient, #buildserver, #buildassets, #buildassetsprefix, #buildserverentry, #buildredirects, #buildinlinestylesheets, #buildconcurrency, #server-options, #serverhost, #serverport, #serverallowedhosts, #serveropen, #serverheaders, #session-options, #sessiondriver, #sessionoptions, #sessioncookie, #sessionttl, #dev-toolbar-options, #devtoolbarenabled, #prefetch-options, #prefetchprefetchall, #prefetchdefaultstrategy, #image-options, #imageendpoint, #imageservice, #imageserviceconfiglimitinputpixels, #imagedomains, #imageremotepatterns, #imageexperimentallayout, #imageexperimentalobjectfit, #imageexperimentalobjectposition, #imageexperimentalbreakpoints, #experimentaldefaultstyles, #markdown-options, #markdownshikiconfig, #markdownsyntaxhighlight, #markdownsyntaxhighlighttype, #markdownsyntaxhighlightexcludelangs, #markdownremarkplugins, #markdownrehypeplugins, #markdowngfm, #markdownsmartypants, #markdownremarkrehype, #i18n, #i18nlocales, #i18ndefaultlocale, #i18nfallback, #example, #i18nrouting, #i18nroutingprefixdefaultlocale, #i18nroutingredirecttodefaultlocale, #i18nroutingfallbacktype, #i18ndomains, #env, #envschema, #envvalidatesecrets, #docsearch-lvl0, #learn-astro-course-1

@sarah11918 sarah11918 May 28, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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. You can override them with your own styles, or disable them entirely by setting [`image.experimentalDefaultStyles`](/en/reference/configuration-reference/#imageexperimentaldefaultstyles) to `false` if you prefer to handle styling them yourself.
The responsive image component applies a small number of styles to ensure images 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. You can disable them by setting [`image.experimentalDefaultStyles`](/en/reference/configuration-reference/#imageexperimentaldefaultstyles) to `false` if you prefer to handle styling them yourself.

The "override or disable" made it sound like you could access these directly to rewrite, but really, if you set this to false, they just ARE disabled, right?

@ascorbic ascorbic May 28, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can override them with your own styles (like any CSS) without disabling them, so it should be the default choice if someone just wants to change a single thing. It's only really Tailwind 4 that can't do it like that

@sarah11918 sarah11918 May 28, 2025 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, the sentence before could be taken ambiguously as in "by setting false, you can override or disable". ~~(Since here, we're defining what the config option does) oops, this is not the config ref part!

Let me take a shot at it so it's clear that the config option refers only to disabling entirely.


These are the default styles:

```css title="Responsive Image Styles"
:where([data-astro-image]) {
Expand All @@ -167,6 +169,6 @@

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.

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).
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.

Check failure on line 172 in src/content/docs/en/reference/experimental-flags/responsive-images.mdx

View workflow job for this annotation

GitHub Actions / Check Links 

Broken fragment link in src/content/docs/en/reference/experimental-flags/responsive-images.mdx, line 172: The linked page does not contain a fragment with the name "#imageexperimentaldefaultstyles". Available fragments: #theme-icons, #gradient, #starlight__sidebar, #__tab-start, #__tab-guides-and-recipes, #__tab-reference, #__tab-integrations, #__tab-third-party-services, #starlight__mobile-toc, #starlight__on-this-page--mobile, #starlight__on-this-page, #learn-astro-course-2, #_top, #top-level-options, #site, #base, #trailingslash, #redirects, #output, #adapter, #integrations, #root, #examples, #srcdir, #publicdir, #outdir, #cachedir, #compresshtml, #scopedstylestrategy, #security, #securitycheckorigin, #vite, #examples-1, #build-options, #buildformat, #effect-on-astrourl, #buildclient, #buildserver, #buildassets, #buildassetsprefix, #buildserverentry, #buildredirects, #buildinlinestylesheets, #buildconcurrency, #server-options, #serverhost, #serverport, #serverallowedhosts, #serveropen, #serverheaders, #session-options, #sessiondriver, #sessionoptions, #sessioncookie, #sessionttl, #dev-toolbar-options, #devtoolbarenabled, #prefetch-options, #prefetchprefetchall, #prefetchdefaultstrategy, #image-options, #imageendpoint, #imageservice, #imageserviceconfiglimitinputpixels, #imagedomains, #imageremotepatterns, #imageexperimentallayout, #imageexperimentalobjectfit, #imageexperimentalobjectposition, #imageexperimentalbreakpoints, #experimentaldefaultstyles, #markdown-options, #markdownshikiconfig, #markdownsyntaxhighlight, #markdownsyntaxhighlighttype, #markdownsyntaxhighlightexcludelangs, #markdownremarkplugins, #markdownrehypeplugins, #markdowngfm, #markdownsmartypants, #markdownremarkrehype, #i18n, #i18nlocales, #i18ndefaultlocale, #i18nfallback, #example, #i18nrouting, #i18nroutingprefixdefaultlocale, #i18nroutingredirecttodefaultlocale, #i18nroutingfallbacktype, #i18ndomains, #env, #envschema, #envvalidatesecrets, #docsearch-lvl0, #learn-astro-course-1

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).
Loading