feat: Add support for background size cover, contain and auto

README.md

@@ -206,7 +206,7 @@ Satori uses the same Flexbox [layout engine](https://yogalayout.com) as React Na
 <tr><td><code>backgroundColor</code></td><td>Supported, single value</td><td></td></tr>
 <tr><td><code>backgroundImage</code></td><td><code>linear-gradient</code>, <code>repeating-linear-gradient</code>, <code>radial-gradient</code>, <code>repeating-radial-gradient</code>, <code>url</code>, single value</td><td></td></tr>
 <tr><td><code>backgroundPosition</code></td><td>Support single value</td><td></td></tr>
-<tr><td><code>backgroundSize</code></td><td>Support two-value size i.e. <code>10px 20%</code></td><td></td></tr>
+<tr><td><code>backgroundSize</code></td><td>Support <code>cover</code>, <code>contain</code>, <code>auto</code>, and two-value sizes i.e. <code>10px 20%</code></td><td><a href="https://og-playground.vercel.app/?share=ZZXXjqNIFIZfpeWb2RW9Itik3tmRwAQDJgeDNTfkHEwwYdTvvnhGWq003HDOqZ8fDlX11Y9D2Ebx4ePwNcqf35u3t2Fcq_ifHz9e8dtbFudpNn68wRD0_qsy59GY_b8Q-GGZ9u3UREbcxf4u_tK0f_U_4y-_acx8i3dF2Dajnze_jwu1n74EU1_9Efmj_5G_CmDXpH8H_hBjp_fcoVVjhiQ-ban9Ukw7Y-10j3j9ldtnyttvND6LubMHTABVrO4YJypeXGSdBtuwwCRWANMRpy7W49jmUFvuyU0fnmZeduAiZ6ZZaueUXM0V5VDBNs2OtfX6MimW0iTTBD0JeYbFeSOrpLGR5_iMkrHGYSAGEFJl77xRCsjNDC_MmIHV8KDOdsboszJAXchEZifrokEtSyrT5cUkbkifODIuyKC2oblXy8yAqyt-VLcJr8UhYJc2PGoWrW4dppebvMnexThypKZD-IRPx2dFjjnj3eAxqMU1XLTipNKFhrv-1Te3ZWE41aKHtHUogVtC98ZlniyqI9lkcOS5xQnRSlTV0-tKaHckalSGADnQlda0i12YNG7wcO3J-IrGTiWLXtviZ6tc1LDpTrmyhe5uybE1CSYwMHinsikaLkdSepmcxdufvxhlwGcYZFBUF9yqXt9fIT5MC0L3H99JUi4UOqz4PPHkFsq72zM8WjYnYGqRWukUlGh4gcFkBi7zyiOuA0c-D4-VW-zWoSnBLSFHV2qkeLMWcwGd7jWpWVCi5AgElPbN7TB1vJpQbagUW4USzTgmUwZs5ckWiKtbeoovGVYKVZYplg37_NjrsGiWVdUBSYO2HADFotULPEJ1kl-3_QMDRpkEjjNQJkq5rpYMXk6gMN14z9Nh9lIhURHsoqlSm5QUTb2sFTs1ag4JjyqDx8eRoJY24GdbW3E7mrfC2jYpulOIfsX9q8znWkYJIU1Lpl3RHbd1jvHq2hVJ27w8Hu0DQtHereC9qSlsH2pBzdY8HbMclOVBaxkCNQPbCS280YnTjDj1vRVdXk2GTcHUtcLIC2kuZmc-F0CjT5O0bxLguUZX0-46gocAOemyO9ud16EQRYoEzoUHKbUT2c6Z6iVo8ikGz_c28GlfMMZFXId-3ndkk55Y6pEpLu00ERw5DiE5ibPw6Jg0pxiXMCDPY5Xv0ooyy07SOY2ItUJA0GcAc95NKKS17ERr91XBFBjo7kTiSi-nM-MjY9_WyXH_6BRO6OxOPK9k9bA925tNd9HmcmRzKI6YXmAFWWNmoOixTTtukLU1GRFeZIuaqTM24QNH063N0Ubq86kAJkdSfl7B89Dt0_KkVXVtMRYgb4Wsogggys-O-89XYZGtuDtasBrKY6ZmsIg42314VQNix3wBqQC70a0ODgxY3BbqKvgnxsscyioJTTAUoJHSrXUiwWwtLqtAakcVCILGBrn4C1p0-WKUzlCXhIAKTFUJTXzV9zXLWaU56fX5_OfvsDy3VdvvsJyzfIy_vEY_P783376CO8u_fW8O74e2G_O2GQ4fPw4_wX34IHZwH35h_fBxeiVRHEzp4SPxqyF-P8R1W-TW2r3OhHH-me0-yc5rtg7i6PAx9lP8-X4Y_WBXZHFVtXPbV9Hh818">Example</a></td></tr>
 <tr><td><code>backgroundClip</code></td><td><code>border-box</code>, <code>text</code></td><td></td></tr>
 <tr><td><code>backgroundRepeat</code></td><td><code>repeat</code>, <code>repeat-x</code>, <code>repeat-y</code>, <code>no-repeat</code>, defaults to <code>repeat</code></td><td></td></tr>
 

src/builder/background-image.ts

@@ -24,6 +24,61 @@ function toAbsoluteValue(v: string | number, base: number) {
   return +v
 }
 
+function calculateKeywordSize(
+  keyword: string,
+  containerWidth: number,
+  containerHeight: number,
+  imageWidth: number,
+  imageHeight: number
+): [number, number] {
+  if (!imageWidth || !imageHeight) {
+    return [containerWidth, containerHeight]
+  }
+
+  if (keyword === 'cover') {
+    // Scale to cover the container (use max scale to ensure it covers)
+    const scaleX = containerWidth / imageWidth
+    const scaleY = containerHeight / imageHeight
+    const scale = Math.max(scaleX, scaleY)
+    return [imageWidth * scale, imageHeight * scale]
+  }
+
+  if (keyword === 'contain') {
+    // Scale to fit within the container (use min scale to ensure it fits)
+    const scaleX = containerWidth / imageWidth
+    const scaleY = containerHeight / imageHeight
+    const scale = Math.min(scaleX, scaleY)
+    return [imageWidth * scale, imageHeight * scale]
+  }
+
+  // For 'auto' or other values, handle auto
+  if (keyword === 'auto' || keyword.includes('auto')) {
+    const parts = keyword.split(' ')
+    const widthPart = parts[0] || 'auto'
+    const heightPart = parts[1] || parts[0] || 'auto'
+
+    let finalWidth = imageWidth
+    let finalHeight = imageHeight
+
+    if (widthPart === 'auto' && heightPart !== 'auto') {
+      // Width is auto, height is specified
+      const parsedHeight = toAbsoluteValue(heightPart, containerHeight)
+      finalHeight = parsedHeight
+      finalWidth = (imageWidth / imageHeight) * parsedHeight
+    } else if (heightPart === 'auto' && widthPart !== 'auto') {
+      // Height is auto, width is specified
+      const parsedWidth = toAbsoluteValue(widthPart, containerWidth)
+      finalWidth = parsedWidth
+      finalHeight = (imageHeight / imageWidth) * parsedWidth
+    }
+    // If both are auto, use intrinsic dimensions
+
+    return [finalWidth, finalHeight]
+  }
+
+  return [containerWidth, containerHeight]
+}
+
 function parseLengthPairs(
   str: string,
   {
@@ -76,12 +131,35 @@ export default async function backgroundImage(
   const repeatX = repeat === 'repeat-x' || repeat === 'repeat'
   const repeatY = repeat === 'repeat-y' || repeat === 'repeat'
 
-  const dimensions = parseLengthPairs(size, {
-    x: width,
-    y: height,
-    defaultX: width,
-    defaultY: height,
-  })
+  // Check if size is a keyword (cover, contain, auto) that needs to be calculated later
+  const isKeywordSize =
+    size &&
+    (size === 'cover' ||
+      size === 'contain' ||
+      size === 'auto' ||
+      size.includes('auto'))
+
+  // For gradients, keyword sizes (cover, contain, auto) resolve to the
+  // container dimensions since gradients have no intrinsic size.
+  // For url() images, keyword sizes are calculated later using the image's
+  // intrinsic dimensions.
+  const isGradient =
+    image.startsWith('linear-gradient(') ||
+    image.startsWith('repeating-linear-gradient(') ||
+    image.startsWith('radial-gradient(') ||
+    image.startsWith('repeating-radial-gradient(')
+
+  const dimensions =
+    isKeywordSize && isGradient
+      ? [width, height] // Gradients have no intrinsic size; keyword sizes resolve to container
+      : isKeywordSize
+      ? [0, 0] // Will be calculated later when we have image dimensions
+      : parseLengthPairs(size, {
+          x: width,
+          y: height,
+          defaultX: width,
+          defaultY: height,
+        })
   const offsets = parseLengthPairs(position, {
     x: width,
     y: height,
@@ -118,23 +196,41 @@ export default async function backgroundImage(
   }
 
   if (image.startsWith('url(')) {
-    const dimensionsWithoutFallback = parseLengthPairs(size, {
-      x: width,
-      y: height,
-      defaultX: 0,
-      defaultY: 0,
-    })
     const [src, imageWidth, imageHeight] = await resolveImageData(
       image.slice(4, -1)
     )
-    const resolvedWidth =
-      from === 'mask'
-        ? imageWidth || dimensionsWithoutFallback[0]
-        : dimensionsWithoutFallback[0] || imageWidth
-    const resolvedHeight =
-      from === 'mask'
-        ? imageHeight || dimensionsWithoutFallback[1]
-        : dimensionsWithoutFallback[1] || imageHeight
+
+    let resolvedWidth: number
+    let resolvedHeight: number
+
+    if (isKeywordSize) {
+      // Calculate dimensions based on keyword (cover, contain, auto)
+      const [calcWidth, calcHeight] = calculateKeywordSize(
+        size,
+        width,
+        height,
+        imageWidth,
+        imageHeight
+      )
+      resolvedWidth = calcWidth
+      resolvedHeight = calcHeight
+    } else {
+      // Use the previously parsed dimensions
+      const dimensionsWithoutFallback = parseLengthPairs(size, {
+        x: width,
+        y: height,
+        defaultX: 0,
+        defaultY: 0,
+      })
+      resolvedWidth =
+        from === 'mask'
+          ? imageWidth || dimensionsWithoutFallback[0]
+          : dimensionsWithoutFallback[0] || imageWidth
+      resolvedHeight =
+        from === 'mask'
+          ? imageHeight || dimensionsWithoutFallback[1]
+          : dimensionsWithoutFallback[1] || imageHeight
+    }
 
     return [
       `satori_bi${id}`,

test/image.test.tsx

@@ -664,6 +664,74 @@ describe('background-image: url()', () => {
     expect(toImage(svg, 100)).toMatchImageSnapshot()
   })
 
+  it('should support background-size: cover', async () => {
+    const svg = await satori(
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          backgroundImage: `url(${PNG_SAMPLE})`,
+          backgroundSize: 'cover',
+        }}
+      ></div>,
+      { width: 100, height: 100, fonts }
+    )
+
+    expect(toImage(svg, 100)).toMatchImageSnapshot()
+  })
+
+  it('should support background-size: contain', async () => {
+    const svg = await satori(
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          backgroundImage: `url(${PNG_SAMPLE})`,
+          backgroundSize: 'contain',
+        }}
+      ></div>,
+      { width: 100, height: 100, fonts }
+    )
+
+    expect(toImage(svg, 100)).toMatchImageSnapshot()
+  })
+
+  it('should support background-size: auto', async () => {
+    const svg = await satori(
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          backgroundImage: `url(${PNG_SAMPLE})`,
+          backgroundSize: 'auto',
+        }}
+      ></div>,
+      { width: 100, height: 100, fonts }
+    )
+
+    expect(toImage(svg, 100)).toMatchImageSnapshot()
+  })
+
+  it('should support background-size: cover with non-square container', async () => {
+    const svg = await satori(
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          backgroundImage: `url(${PNG_SAMPLE})`,
+          backgroundSize: 'cover',
+        }}
+      ></div>,
+      { width: 200, height: 100, fonts }
+    )
+
+    expect(toImage(svg, 200)).toMatchImageSnapshot()
+  })
+
   it('should correctly position the background pattern', async () => {
     const svg = await satori(
       <div