Update experimental responsive image docs #11513
Conversation
ascorbic
added
the
merge-on-release
✅ Deploy Preview for astro-docs-2 ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Lunaria Status Overview🌕 This pull request will trigger status changes. Learn moreBy default, every PR changing files present in the Lunaria configuration's You can change this by adding one of the keywords present in the Tracked Files
Warnings reference
|
There was a problem hiding this comment.
Looks great! Just a few comments, mostly just breaking text up into more paragraphs.
I made two suggestions for the new image layout options list, because I think it's helpful that all of them have a "use for/useful for" ... these might not be the best choices, but I think if we can put something concrete in there, that will help people choose!
src/content/docs/en/reference/experimental-flags/responsive-images.mdx
Outdated
Show resolved
Hide resolved
src/content/docs/en/reference/experimental-flags/responsive-images.mdx
Outdated
Show resolved
Hide resolved
|
|
||
| In order to generate the correct `srcset` and `sizes` attributes, the `<Image />` and `<Picture />` components need to know how the image should resize when its container changes size. This is done by setting the `layout` prop, or `image.experimentalLayout` default. The supported values are: | ||
|
|
||
| - `constrained` - The image will scale to fit the container, maintaining its aspect ratio, but will not exceed the specified `width` and `height`, or the image's original dimensions. |
There was a problem hiding this comment.
| - `constrained` - The image will scale to fit the container, maintaining its aspect ratio, but will not exceed the specified `width` and `height`, or the image's original dimensions. | |
| - `constrained` - The image will scale to fit the container, maintaining its aspect ratio, but will not exceed the specified `width` and `height`, or the image's original dimensions. Use this for images that should be responsive, but only when smaller than the original (or a specified) size. |
I like how the others had a "Use this/this is useful" so something like this maybe?
There was a problem hiding this comment.
I've done new wording, including saying that if they're unsure they should choose this, and that it matches the default Tailwind styles
|
|
||
| - `constrained` - The image will scale to fit the container, maintaining its aspect ratio, but will not exceed the specified `width` and `height`, or the image's original dimensions. | ||
| - `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. The `srcset` will be generated for the requested image size, plus 2x resolution for high-density displays if the source image is large enough. |
There was a problem hiding this comment.
| - `fixed` - The image will maintain the requested dimensions and not resize. The `srcset` will be generated for the requested image size, plus 2x resolution for high-density displays if the source image is large enough. | |
| - `fixed` - The image will maintain the requested dimensions and not resize. The `srcset` will be generated for the requested image size, plus 2x resolution for high-density displays if the source image is large enough. Use this when you prefer to see your image cropped at smaller sizes instead of showing a smaller version of the whole picture. |
OK, I don't love this, but I do think an explanation of the container making only part of the image visible, at its original size, is helpful here for the Use when.../Useful for...
There was a problem hiding this comment.
I clearly need to explain this better, because this isn't what it does! It just displays them with no resizing at all, like a normal img tag with no styling.
There was a problem hiding this comment.
I've rewritten this to try and make it clearer. lmk if it makes sense!
Co-authored-by: Sarah Rainsberger <[email protected]>
sarah11918
added
the
improve or update documentation
|
No, it's in this release: withastro/astro#13676 |
|
Also merge #11532 when this is merged! |
3 participants
Description (required)
Updates the experimental flag docs to reflect the changes in withastro/astro#13677. It also expands the docs to explain the feature in more detail, including explanations of why to use it, and a note about potential impact on build times. It adds a note on use with Tailwind 4.
Related issues & labels (optional)