adds ImageTransform.background

.changeset/shaky-bananas-clap.md

@@ -0,0 +1,23 @@
+---
+'astro': minor
+---
+
+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, 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.
+
+```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)

packages/astro/src/assets/consts.ts

@@ -34,4 +34,5 @@ export const DEFAULT_HASH_PROPS = [
 	'quality',
 	'fit',
 	'position',
+	'background',
 ];

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;

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) {

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;