From 2cb479f4bacb38d83bff93c89a76ec1878dd2a45 Mon Sep 17 00:00:00 2001
From: Julien Cayzac <julien.cayzac@rakuten.com>
Date: Fri, 9 Jan 2026 13:25:25 +0900
Subject: [PATCH 1/3] add ImageTransform.background

fix outdated comment

add missing url param handling, and remove support for object

move sharp's flatten() after any resize()
---
 .changeset/shaky-bananas-clap.md              | 5 +++++
 packages/astro/src/assets/consts.ts           | 1 +
 packages/astro/src/assets/services/service.ts | 6 +++++-
 packages/astro/src/assets/services/sharp.ts   | 7 +++++++
 packages/astro/src/assets/types.ts            | 1 +
 5 files changed, 19 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/shaky-bananas-clap.md

diff --git a/.changeset/shaky-bananas-clap.md b/.changeset/shaky-bananas-clap.md
new file mode 100644
index 000000000000..96dbd96bfc5b
--- /dev/null
+++ b/.changeset/shaky-bananas-clap.md
@@ -0,0 +1,5 @@
+---
+'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`.
diff --git a/packages/astro/src/assets/consts.ts b/packages/astro/src/assets/consts.ts
index 5fae641ae462..5ca3809df906 100644
--- a/packages/astro/src/assets/consts.ts
+++ b/packages/astro/src/assets/consts.ts
@@ -34,4 +34,5 @@ export const DEFAULT_HASH_PROPS = [
 	'quality',
 	'fit',
 	'position',
+	'background',
 ];
diff --git a/packages/astro/src/assets/services/service.ts b/packages/astro/src/assets/services/service.ts
index 0ce8fbd4c338..0c5b4b008032 100644
--- a/packages/astro/src/assets/services/service.ts
+++ b/packages/astro/src/assets/services/service.ts
@@ -111,7 +111,7 @@ export interface LocalImageService<T extends Record<string, any> = Record<string
 	/**
 	 * A list of properties that should be used to generate the hash for the image.
 	 *
-	 * Generally, this should be all the properties that can change the result of the image. By default, this is `src`, `width`, `height`, `quality`, and `format`.
+	 * Generally, this should be all the properties that can change the result of the image. By default, this is `src`, `width`, `height`, `format`, `quality`, `fit`, `position`, and `background`.
 	 */
 	propertiesToHash?: string[];
 }
@@ -124,6 +124,7 @@ export type BaseServiceTransform = {
 	quality?: string | null;
 	fit?: ImageFit;
 	position?: string;
+	background?: string;
 };
 
 const sortNumeric = (a: number, b: number) => a - b;
@@ -254,6 +255,7 @@ export const baseService: Omit<LocalImageService, 'transform'> = {
 			priority,
 			fit,
 			position,
+			background,
 			...attributes
 		} = options;
 		return {
@@ -363,6 +365,7 @@ export const baseService: Omit<LocalImageService, 'transform'> = {
 			f: 'format',
 			fit: 'fit',
 			position: 'position',
+			background: 'background',
 		};
 
 		Object.entries(params).forEach(([param, key]) => {
@@ -397,6 +400,7 @@ export const baseService: Omit<LocalImageService, 'transform'> = {
 			quality: params.get('q'),
 			fit: params.get('fit') as ImageFit,
 			position: params.get('position') ?? undefined,
+			background: params.get('background') ?? undefined,
 		};
 
 		return transform;
diff --git a/packages/astro/src/assets/services/sharp.ts b/packages/astro/src/assets/services/sharp.ts
index 82646ffdeeeb..d89449a9b6e1 100644
--- a/packages/astro/src/assets/services/sharp.ts
+++ b/packages/astro/src/assets/services/sharp.ts
@@ -100,6 +100,13 @@ const sharpService: LocalImageService<SharpImageServiceConfig> = {
 			});
 		}
 
+		// If background is set, flatten the image with the specified background.
+		// We do this after resize to ensure the background covers the entire image
+		// even if its size has expanded.
+		if (transform.background) {
+			result.flatten({ background: transform.background });
+		}
+
 		if (transform.format) {
 			let quality: number | string | undefined = undefined;
 			if (transform.quality) {
diff --git a/packages/astro/src/assets/types.ts b/packages/astro/src/assets/types.ts
index 820988ec7e91..c96befc9e91f 100644
--- a/packages/astro/src/assets/types.ts
+++ b/packages/astro/src/assets/types.ts
@@ -89,6 +89,7 @@ export type ImageTransform = {
 	format?: ImageOutputFormat | undefined;
 	fit?: ImageFit | undefined;
 	position?: string | undefined;
+	background?: string | undefined;
 	[key: string]: any;
 } & Astro.CustomImageProps;
 

From 9d108fda7a2038f7669f3d25b6833760d998bc77 Mon Sep 17 00:00:00 2001
From: Julien Cayzac <julien.cayzac@rakuten.com>
Date: Wed, 14 Jan 2026 12:32:27 +0900
Subject: [PATCH 2/3] embetternification of the changeset

---
 .changeset/shaky-bananas-clap.md | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/.changeset/shaky-bananas-clap.md b/.changeset/shaky-bananas-clap.md
index 96dbd96bfc5b..33b9e89d2bea 100644
--- a/.changeset/shaky-bananas-clap.md
+++ b/.changeset/shaky-bananas-clap.md
@@ -2,4 +2,22 @@
 '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`.
+Adds a new `background` property to the `<Image />` component.
+
+This optional property lets you pass a background color to flatten the image with. By default, when Sharp needs to flatten an image because it's being converted to a format that does not support transparency (e.g. `jpeg`), it uses a black background for that. 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.
+
+```astro
+---
+import { Image } from 'astro:assets';
+---
+<Image
+  src="/transparent.png"
+  alt="A JPEG with a white background!"
+  format="jpeg"
+  background="#ffffff"
+/>
+```
+
+See more about this new property in [the image reference docs](https://docs.astro.build/en/reference/modules/astro-assets/#background)

From f68d125ced324794c3c0f0de8ad3cfd2016caf7f Mon Sep 17 00:00:00 2001
From: Julien Cayzac <jcayzac@users.noreply.github.com>
Date: Sat, 17 Jan 2026 15:35:38 +0900
Subject: [PATCH 3/3] Update .changeset/shaky-bananas-clap.md

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
---
 .changeset/shaky-bananas-clap.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/shaky-bananas-clap.md b/.changeset/shaky-bananas-clap.md
index 33b9e89d2bea..774bb8ba9331 100644
--- a/.changeset/shaky-bananas-clap.md
+++ b/.changeset/shaky-bananas-clap.md
@@ -4,7 +4,7 @@
 
 Adds a new `background` property to the `<Image />` component.
 
-This optional property lets you pass a background color to flatten the image with. By default, when Sharp needs to flatten an image because it's being converted to a format that does not support transparency (e.g. `jpeg`), it uses a black background for that. Providing a value for `background` on an `<Image />` component, or passing it to the `getImage()` helper, will flatten images using that color instead.
+This optional property lets you pass a background color to flatten the image with. By default, Sharp uses a black background when flattening an image that is being converted to a format that does not support transparency (e.g. `jpeg`). 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.