feat: svg rasterization upgrade guide #13039
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for astro-docs-2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
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
|
sarah11918
added
6.0
merge-on-release
delucis
approved these changes
Jan 13, 2026
Member
delucis
left a comment
delucis
left a comment
There was a problem hiding this comment.
This looks great — thanks for taking care of it @Princesseuh!
Left one small nit, but otherwise LGTM.
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
sarah11918
reviewed
Jan 13, 2026
Member
sarah11918
left a comment
sarah11918
left a comment
There was a problem hiding this comment.
Thanks @Princesseuh ! As a breaking change, this should go in one of the categories below with a full entry below linking to the PR, following the format of the others.
Left some suggestions below as to what that could look like!
Comment on lines
+167
to
+169
| ### SVG rasterization | ||
|
|
||
| Astro's default Sharp image service now supports converting SVG files to raster files (such as PNG, WebP, etc.). Note that this is subject to many limitations, for instance SVGs with embedded fonts might not be converted properly. |
Member
There was a problem hiding this comment.
Suggested change
| ### SVG rasterization | |
| Astro's default Sharp image service now supports converting SVG files to raster files (such as PNG, WebP, etc.). Note that this is subject to many limitations, for instance SVGs with embedded fonts might not be converted properly. | |
| ### Changed: SVG rasterization | |
| In Astro v5.x, Astro's default Sharp image service was unable to convert SVG files to raster files (e.g. PNG, WebP). This meant that the `<Image />` component would ignore any value set for `format` when optimizing and transforming SVG files. | |
| Astro 6.0 now supports SVG rasterization. This is subject to many limitations, for instance SVGs with embedded fonts might not be converted properly. However, when the `format` property is set, the image service will now attempt to convert SVG images. |
Something like this would fit our pattern. Please edit if incorrect or not the most helpful way to describe this!
|
|
||
| #### What should I do? | ||
|
|
||
| If you were previously relying on code like this to automatically skip SVGs: |
Member
There was a problem hiding this comment.
Suggested change
| If you were previously relying on code like this to automatically skip SVGs: | |
| If you were previously relying the fact that the image service would automatically skip converting SVGs, you must now check for the format of your images beforehand to avoid converting SVGs to raster images: |
Comment on lines
+175
to
+187
| ```astro | ||
| <Image src={imageThatMightBeAnSvg} format="avif" alt="example" /> | ||
| ``` | ||
|
|
||
| You'll now need to check the format beforehand to avoid converting SVGs to raster images: | ||
|
|
||
| ```astro {3} | ||
| <Image | ||
| src={imageThatMightBeAnSvg} | ||
| format={imageThatMightBeAnSvg.src.format === "svg" ? "svg" : "avif"} | ||
| alt="example" | ||
| /> | ||
| ``` |
Member
There was a problem hiding this comment.
Suggested change
| ```astro | |
| <Image src={imageThatMightBeAnSvg} format="avif" alt="example" /> | |
| ``` | |
| You'll now need to check the format beforehand to avoid converting SVGs to raster images: | |
| ```astro {3} | |
| <Image | |
| src={imageThatMightBeAnSvg} | |
| format={imageThatMightBeAnSvg.src.format === "svg" ? "svg" : "avif"} | |
| alt="example" | |
| /> | |
| ``` | |
| ```astro del={1} ins=(3-7} | |
| <Image src={imageThatMightBeAnSvg} format="avif" alt="example" /> | |
| <Image | |
| src={imageThatMightBeAnSvg} | |
| format={imageThatMightBeAnSvg.src.format === "svg" ? "svg" : "avif"} | |
| alt="example" | |
| /> | |
| ``` | |
| <ReadMore>Learn more about [the `format` image property](/en/reference/modules/astro-assets/#format)</ReadMore> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description (required)
withastro/astro#15180 coming in v6!