From e0e3e2fc89c6798041007948866c94d8e857b2bc Mon Sep 17 00:00:00 2001
From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
Date: Mon, 26 Jan 2026 15:18:41 -0400
Subject: [PATCH] add `background` property to `astro:assets`

---
 .../en/reference/modules/astro-assets.mdx     | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/src/content/docs/en/reference/modules/astro-assets.mdx b/src/content/docs/en/reference/modules/astro-assets.mdx
index c7176b70b1de5..c52dcc75491c2 100644
--- a/src/content/docs/en/reference/modules/astro-assets.mdx
+++ b/src/content/docs/en/reference/modules/astro-assets.mdx
@@ -324,6 +324,33 @@ fetchpriority="high"
 
 These individual attributes can still be set manually if you need to customize them further.
 
+#### `background`
+
+<p>
+
+**Type:** `string | undefined`<br />
+<Since v="5.17.0" />
+</p>
+
+The background color to use when flattening an image to transform it into the requested output `format`.
+
+By default, Sharp uses a black background when flattening an image. Specifying a different background color is especially useful when transforming images with transparent backgrounds to a format that does not support transparency (e.g. `jpeg`):
+
+```astro title="src/components/MyComponent.astro" "background"
+---
+import { Image } from 'astro:assets';
+import myImage from '../assets/my_image.png';
+---
+<Image
+  src={myImage}
+  alt="A description of my image"
+  format="jpeg"
+  background="#ffffff"
+/>
+```
+
+Values are passed directly to the image service. Sharp accepts [any value the `color-string` package can parse](https://github.com/Qix-/color-string/blob/master/README.md#parsing).
+
 ### `<Picture />`
 
 <p><Since v="3.3.0" /></p>