adds ImageTransform.background #15153

jcayzac · 2026-01-09T04:33:01Z

Changes

This adds support for providing a background color in image transforms. Right now Astro has no support for that, so the background of anything converted to e.g. jpeg is always Sharp's default black.

Testing

I'd need some help figuring how to implement a test for this. Is there a way to render a JPEG to a <canvas> in a headless browser inside Astro tests?

Docs

Some documentation updates are definitely needed for this, to document the new field.

/cc @withastro/maintainers-docs for feedback!

changeset-bot · 2026-01-09T04:33:07Z

🦋 Changeset detected

Latest commit: f68d125

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

codspeed-hq · 2026-01-09T04:45:09Z

Merging this PR will not alter performance

✅ 9 untouched benchmarks

_{Comparing jcayzac:jpeg-background (f68d125) with main (94ac011)}

packages/astro/src/assets/services/service.ts

jcayzac · 2026-01-09T06:07:01Z

I missed a few other spots that needed updating. Doing that now.

@Princesseuh Could you explain why this doesn't check other things for equality, e.g. quality ?

astro/packages/astro/src/assets/internal.ts

Lines 172 to 175 in 34f84c2

    
           const matchesValidatedTransform = (transform: ImageTransform) => 
        
           	transform.width === validatedOptions.width && 
        
           	transform.height === validatedOptions.height && 
        
           	transform.format === validatedOptions.format;

Edit: Ah, I think I get it! But now I don't get why format is included. It should only be width and height. We already know that everything else matches.

jcayzac · 2026-01-09T06:40:51Z

Alright, everything fixed now.
I removed support for passing an object with r, g, b and alpha values, albeit supported by Sharp, as to not make the URL params more complicate than the existing. Only string is supported now, although users can still pass rgba(r b g / alpha).

Princesseuh · 2026-01-09T09:49:47Z

packages/astro/src/assets/services/sharp.ts


+		// if background is set, flatten the image with the specified background
+		if (transform.background) {
+			result.flatten({ background: transform.background });


This property is also relevant for when you crop an image isn't it? I assume it should be passed there as well

@Princesseuh Since we flatten() when it's set, any subsequent resize() will be on the flattened image that has the background already.

@Princesseuh …but, it might actually make sense to flatten() only after any resize(), since this means less pixel operations. Would you want me to move it there?

@Princesseuh Since we flatten() when it's set, any subsequent resize() will be on the flattened image that has the background already.

But can't a resize introduce new alpha depending on the cropping strategy? Would it include the background?

@Princesseuh you're right, I don't know if Sharp keeps a state of "oh this image is flattened now, so if the canvas expands I should fill it with this background color". I think it's safer to move flatten() at the end. I'll do that now.

@Princesseuh Done!

Princesseuh

This is good with me!

sarah11918

Thanks for providing this new feature! Left a note on the kind of changeset message we'd typically like to have!

Also, for further docs, we need to add an API reference for the new option in this section: https://docs.astro.build/en/reference/modules/astro-assets/#imagetransform (I think it's fine to add it to the end of the list, after position)

And, for example, if this is something actually set on the <Image /> component itself, then it would need to be added here https://docs.astro.build/en/reference/modules/astro-assets/#image- (I think it's fine to stick it on at the end, after priority.)

You can follow the model for the existing properties in each place this is needed. Under ImageTransform you can see the descriptions are very minimal. Properties of the <Image /> component include an initial API reference block and then the content can be something like the changeset content here, but un-hyped. Just a matter-of-fact explanation of what it is/does, and an example showing it in use.

As I explain below, I'm not sure where the user sets this value, so the key point is to make sure that it's obvious to the reader how to get started and use this new feature. That's where I'll need your help!

sarah11918 · 2026-01-13T13:01:47Z

.changeset/shaky-bananas-clap.md

+'astro': minor
+---
+
+Add `background` in `ImageTransform`, to allow flattening images with the given background color. This is especially useful when the requested output format doesn't support an alpha channel, e.g. `jpeg`.


Just a note here that for a minor release of a new feature, we'd usually hype it up a bit more, focusing on what a user can now do (with an example usage shown) rather than implementation details. You can see a model of this in our contributing docs.

In this case, I suspect that maybe talking about the ImageTransform type here, and possibly even flattening, is more of an implementation detail? More commonly, we'd stick to wording that closer describes what someone is trying to achieve, like in the PR description itself ("providing a background color in image transforms.")

You are the subject matter expert here, and I don't really have a good idea of how this is used: added as a property on the <Image /> component which will then be used when the image is transformed? Is this passed when using something like one of the image transform functions?

So this is just very rough, and I'm only throwing words together; may not be accurate, but we'd expect a changeset for a new feature added to guide someone though what it looks like to use the new feature something like:

Adds a new `background` property to the `<Image />` component This optional property allows you to provide a background color for image transformations. By default, images converted to another format by Sharp use a default black background. Providing a value for `background` on an `<Image />` component, or passing it to the `getImage()` helper, will flatten images using that color instead. This is especially useful when the requested output format doesn't support an alpha channel (e.g. `jpeg`) and can't support transparent backgrounds. ``` show an example of this in use ``` See more about this new property in [the image reference docs](https://docs.astro.build/en/reference/modules/astro-assets/#background)

That's the general idea anyway:

Quick sentence to shout "New! Shiny!" and grab people's attention without a lot of visual clutter

describe the problem it solves or ability it unlocks and why that's cool

show an example that people could copy into their projects right away to try it out so that it's easy for them to get started

link to the docs for the new thing

You know the feature better than I do, so you'll need to describe what makes sense to show it off, but that's the pattern!

Thanks! I'll make the necessary changes over the weekend.

Regarding the reference docs, those should probably mention that

background supports any syntax supported by color-string.

@sarah11918 I see you're hardcoding the locale in https://docs.astro.build/en/reference/modules/astro-assets/ instead of relying on the automatic resolution of the current locale using https://docs.astro.build/reference/modules/astro-assets/. Is this what's expected? I'm OK with it but I think it can lead to links in a bogus locale incorrectly leaking into translations.

@sarah11918 How is the new changeset?

Changeset is good @jcayzac ! See my one tiny suggestion.

https://docs.astro.build/en/reference/modules/astro-assets/ instead of relying on the automatic resolution of the current locale using https://docs.astro.build/reference/modules/astro-assets/. Is this what's expected?

All docs links are written with a locale, even the English ones. That's the URL people will arrive at anyway, and always see in their browser, so no reason to create a redirect!

fix outdated comment add missing url param handling, and remove support for object move sharp's flatten() after any resize()

sarah11918

This PR is looking great to me! (One small suggestion). Just a reminder that we don't merge this PR or consider the feature done until docs are added, though, so please do make a Docs PR to add background! You can follow the existing examples, and if you need it find info on how we document the API references (yes, including the line break 😅 ) in the contributing guide here: https://contribute.docs.astro.build/reference/api-references/

.changeset/shaky-bananas-clap.md

sarah11918 · 2026-01-15T17:55:02Z

.changeset/shaky-bananas-clap.md

+'astro': minor
+---
+
+Add `background` in `ImageTransform`, to allow flattening images with the given background color. This is especially useful when the requested output format doesn't support an alpha channel, e.g. `jpeg`.


Changeset is good @jcayzac ! See my one tiny suggestion.

https://docs.astro.build/en/reference/modules/astro-assets/ instead of relying on the automatic resolution of the current locale using https://docs.astro.build/reference/modules/astro-assets/. Is this what's expected?

All docs links are written with a locale, even the English ones. That's the URL people will arrive at anyway, and always see in their browser, so no reason to create a redirect!

Co-authored-by: Sarah Rainsberger <[email protected]>

jcayzac · 2026-01-17T06:39:28Z

This PR is looking great to me! (One small suggestion).

@sarah11918 Committed, thanks!

Just a reminder that we don't merge this PR or consider the feature done until docs are added, though, so please do make a Docs PR to add background! You can follow the existing examples, and if you need it find info on how we document the API references (yes, including the line break 😅 ) in the contributing guide here: https://contribute.docs.astro.build/reference/api-references/

@Princesseuh started a PR here. I would like to amend it, but I don't have any push access to the branch she created. Is it OK to make a PR that targets her branch, so we'll merge the combined result to v6?

github-actions bot added the pkg: astro Related to the core `astro` package (scope) label Jan 9, 2026

jcayzac commented Jan 9, 2026

View reviewed changes

packages/astro/src/assets/services/service.ts Outdated Show resolved Hide resolved

jcayzac force-pushed the jpeg-background branch from 15fd3aa to db9458f Compare January 9, 2026 05:07

Princesseuh reviewed Jan 9, 2026

View reviewed changes

Princesseuh approved these changes Jan 9, 2026

View reviewed changes

florian-lefebvre added this to the 5.17.0 milestone Jan 9, 2026

sarah11918 reviewed Jan 13, 2026

View reviewed changes

add ImageTransform.background

2cb479f

fix outdated comment add missing url param handling, and remove support for object move sharp's flatten() after any resize()

jcayzac force-pushed the jpeg-background branch 3 times, most recently from 12902ab to 80da645 Compare January 14, 2026 03:54

embetternification of the changeset

9d108fd

jcayzac force-pushed the jpeg-background branch from 80da645 to 9d108fd Compare January 14, 2026 03:55

sarah11918 reviewed Jan 15, 2026

View reviewed changes

Update .changeset/shaky-bananas-clap.md

f68d125

Co-authored-by: Sarah Rainsberger <[email protected]>

Uh oh!

adds ImageTransform.background #15153

Are you sure you want to change the base?

adds ImageTransform.background #15153

Conversation

jcayzac commented Jan 9, 2026

Changes

Testing

Docs

Uh oh!

changeset-bot bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

codspeed-hq bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

Uh oh!

jcayzac commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jcayzac commented Jan 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jcayzac Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Princesseuh left a comment

Choose a reason for hiding this comment

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jcayzac Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jcayzac commented Jan 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

changeset-bot bot commented Jan 9, 2026 •

edited

Loading

codspeed-hq bot commented Jan 9, 2026 •

edited

Loading

jcayzac commented Jan 9, 2026 •

edited

Loading

jcayzac Jan 9, 2026 •

edited

Loading

jcayzac Jan 14, 2026 •

edited

Loading