facebook · intergalacticspacehighway · Dec 29, 2025
diff --git a/packages/react-native/Libraries/StyleSheet/StyleSheetTypes.js b/packages/react-native/Libraries/StyleSheet/StyleSheetTypes.js
@@ -777,7 +777,15 @@ type RadialGradientValue = {
   }>,
 };
 
-export type BackgroundImageValue = LinearGradientValue | RadialGradientValue;
+type URLBackgroundImageValue = {
+  type: 'url',
+  uri: string | number,
+};
+
+export type BackgroundImageValue =
+  | LinearGradientValue
+  | RadialGradientValue
+  | URLBackgroundImageValue;
 
 export type BackgroundSizeValue =
   | {

diff --git a/packages/react-native/Libraries/StyleSheet/__tests__/processBackgroundImage-test.js b/packages/react-native/Libraries/StyleSheet/__tests__/processBackgroundImage-test.js
@@ -361,6 +361,10 @@ describe('processBackgroundImage', () => {
           {color: 'blue', positions: ['100%']},
         ],
       },
+      {
+        type: 'url',
+        uri: 'https://example.com',
+      },
     ];
     const result = processBackgroundImage(input);
     expect(result).toEqual([
@@ -372,6 +376,10 @@ describe('processBackgroundImage', () => {
           {color: processColor('blue'), position: '100%'},
         ],
       },
+      {
+        type: 'url',
+        uri: 'https://example.com',
+      },
     ]);
   });
 
@@ -1153,4 +1161,104 @@ describe('processBackgroundImage', () => {
     expect(result1).toEqual([]);
     expect(result2).toEqual([]);
   });
+
+  it('should parse url unquoted', () => {
+    const result = processBackgroundImage('url(https://example.com/image.png)');
+    expect(result).toEqual([
+      {type: 'url', uri: 'https://example.com/image.png'},
+    ]);
+  });
+
+  it('should parse url double quoted', () => {
+    const result = processBackgroundImage(
+      'url("https://example.com/image.png")',
+    );
+    expect(result).toEqual([
+      {type: 'url', uri: 'https://example.com/image.png'},
+    ]);
+  });
+
+  it('should parse url single quoted', () => {
+    const result = processBackgroundImage(
+      "url('https://example.com/image.png')",
+    );
+    expect(result).toEqual([
+      {type: 'url', uri: 'https://example.com/image.png'},
+    ]);
+  });
+
+  it('should parse url case insensitive', () => {
+    const result = processBackgroundImage('UrL(https://example.com/image.png)');
+    expect(result).toEqual([
+      {type: 'url', uri: 'https://example.com/image.png'},
+    ]);
+  });
+
+  it('should parse url with query params', () => {
+    const result = processBackgroundImage(
+      'url(https://example.com/image.png?size=Large&format=webp)',
+    );
+    expect(result).toEqual([
+      {
+        type: 'url',
+        uri: 'https://example.com/image.png?size=Large&format=webp',
+      },
+    ]);
+  });
+
+  it('should parse url with whitespace', () => {
+    const result = processBackgroundImage(
+      'url(  https://example.com/image.png  )',
+    );
+    expect(result).toEqual([
+      {type: 'url', uri: 'https://example.com/image.png'},
+    ]);
+  });
+
+  it('should parse multiple urls', () => {
+    const result = processBackgroundImage(
+      'url(https://example.com/bg1.png), url(https://example.com/bg2.png)',
+    );
+    expect(result).toEqual([
+      {type: 'url', uri: 'https://example.com/bg1.png'},
+      {type: 'url', uri: 'https://example.com/bg2.png'},
+    ]);
+  });
+
+  it('should parse url mixed with gradients', () => {
+    const result = processBackgroundImage(
+      'radial-gradient(circle at top left, red, blue), url(https://example.com/image.png), linear-gradient(to bottom, green, yellow)',
+    );
+    expect(result).toEqual([
+      {
+        type: 'radial-gradient',
+        shape: 'circle',
+        size: 'farthest-corner',
+        position: {top: '0%', left: '0%'},
+        colorStops: [
+          {color: processColor('red'), position: null},
+          {color: processColor('blue'), position: null},
+        ],
+      },
+      {type: 'url', uri: 'https://example.com/image.png'},
+      {
+        type: 'linear-gradient',
+        direction: {type: 'angle', value: 180},
+        colorStops: [
+          {color: processColor('green'), position: null},
+          {color: processColor('yellow'), position: null},
+        ],
+      },
+    ]);
+  });
+
+  it('should return empty for url empty', () => {
+    const result = processBackgroundImage('url()');
+    expect(result).toEqual([]);
+  });
+
+  it('should return empty for url empty quoted', () => {
+    const result = processBackgroundImage('url("")');
+    expect(result).toEqual([]);
+  });
 });
diff --git a/packages/react-native/Libraries/StyleSheet/processBackgroundImage.js b/packages/react-native/Libraries/StyleSheet/processBackgroundImage.js
@@ -18,6 +18,7 @@ import type {
   RadialGradientSize,
 } from './StyleSheetTypes';
 
+const resolveAssetSource = require('../Image/resolveAssetSource').default;
 const processColor = require('./processColor').default;
 
 // Linear Gradient
@@ -63,14 +64,20 @@ type RadialGradientBackgroundImage = {
   }>,
 };
 
+type URLBackgroundImage = {
+  type: 'url',
+  uri: string,
+};
+
 // null color indicate that the transition hint syntax is used. e.g. red, 20%, blue
 type ColorStopColor = ProcessedColorValue | null;
 // percentage or pixel value
 type ColorStopPosition = number | string | null;
 
 type ParsedBackgroundImageValue =
   | LinearGradientBackgroundImage
-  | RadialGradientBackgroundImage;
+  | RadialGradientBackgroundImage
+  | URLBackgroundImage;
 
 export default function processBackgroundImage(
   backgroundImage: ?($ReadOnlyArray<BackgroundImageValue> | string),
@@ -84,6 +91,28 @@ export default function processBackgroundImage(
     result = parseBackgroundImageCSSString(backgroundImage.replace(/\n/g, ' '));
   } else if (Array.isArray(backgroundImage)) {
     for (const bgImage of backgroundImage) {
+      if (bgImage.type === 'url') {
+        let uri: ?string = null;
+        if (typeof bgImage.uri === 'string') {
+          uri = bgImage.uri;
+        } else if (typeof bgImage.uri === 'number') {
+          const source = resolveAssetSource(bgImage.uri);
+          if (source != null && source.uri != null) {
+            uri = source.uri;
+          }
+        }
+        if (uri != null) {
+          result = result.concat({
+            type: 'url',
+            uri,
+          });
+          continue;
+        } else {
+          // If the URI is invalid, return an empty array. Same as web.
+          return [];
+        }
+      }
+
       const processedColorStops = processColorStops(bgImage);
       if (processedColorStops == null) {
         // If a color stop is invalid, return an empty array and do not apply any gradient. Same as web.
@@ -250,13 +279,29 @@ function processColorStops(bgImage: BackgroundImageValue): $ReadOnlyArray<{
 function parseBackgroundImageCSSString(
   cssString: string,
 ): $ReadOnlyArray<ParsedBackgroundImageValue> {
-  const gradients = [];
+  const backgroundImages = [];
   const bgImageStrings = splitGradients(cssString);
 
   for (const bgImageString of bgImageStrings) {
+    const urlRegex = /^url\((.*)\)$/i;
+    const urlMatch = urlRegex.exec(bgImageString);
+    if (urlMatch) {
+      let uri = urlMatch[1].trim();
+      const first = uri[0];
+      if ((first === '"' || first === "'") && uri.endsWith(first)) {
+        uri = uri.slice(1, -1);
+      }
+      if (uri.length > 0) {
+        backgroundImages.push({
+          type: 'url',
+          uri,
+        });
+      }
+      continue;
+    }
+
     const bgImage = bgImageString.toLowerCase();
     const gradientRegex = /^(linear|radial)-gradient\(((?:\([^)]*\)|[^()])*)\)/;
-
     const match = gradientRegex.exec(bgImage);
     if (match) {
       const [, type, gradientContent] = match;
@@ -266,11 +311,11 @@ function parseBackgroundImageCSSString(
         : parseLinearGradientCSSString(gradientContent);
 
       if (gradient != null) {
-        gradients.push(gradient);
+        backgroundImages.push(gradient);
       }
     }
   }
-  return gradients;
+  return backgroundImages;
 }
 
 function parseRadialGradientCSSString(

diff --git a/...act-native/ReactCommon/react/renderer/components/view/BackgroundImagePropsConversions.cpp b/...act-native/ReactCommon/react/renderer/components/view/BackgroundImagePropsConversions.cpp
@@ -210,6 +210,14 @@ void parseProcessedBackgroundImage(
       }
 
       backgroundImage.emplace_back(std::move(radialGradient));
+    } else if (type == "url") {
+      auto uriIt = rawBackgroundImageMap.find("uri");
+      if (uriIt != rawBackgroundImageMap.end() &&
+          uriIt->second.hasType<std::string>()) {
+        URLBackgroundImage urlBackgroundImage;
+        urlBackgroundImage.uri = (std::string)(uriIt->second);
+        backgroundImage.emplace_back(std::move(urlBackgroundImage));
+      }
     }
   }
 
@@ -415,6 +423,14 @@ void parseUnprocessedBackgroundImageList(
       }
 
       backgroundImage.emplace_back(std::move(radialGradient));
+    } else if (type == "url") {
+      auto uriIt = rawBackgroundImageMap.find("uri");
+      if (uriIt != rawBackgroundImageMap.end() &&
+          uriIt->second.hasType<std::string>()) {
+        URLBackgroundImage urlBackgroundImage;
+        urlBackgroundImage.uri = (std::string)(uriIt->second);
+        backgroundImage.emplace_back(std::move(urlBackgroundImage));
+      }
     }
   }
 
@@ -478,6 +494,13 @@ void fromCSSColorStop(
 
 std::optional<BackgroundImage> fromCSSBackgroundImage(
     const CSSBackgroundImageVariant& cssBackgroundImage) {
+  if (std::holds_alternative<CSSURLFunction>(cssBackgroundImage)) {
+    const auto& urlFunc = std::get<CSSURLFunction>(cssBackgroundImage);
+    URLBackgroundImage urlBackgroundImage;
+    urlBackgroundImage.uri = urlFunc.url;
+    return BackgroundImage{urlBackgroundImage};
+  }
+
   if (std::holds_alternative<CSSLinearGradientFunction>(cssBackgroundImage)) {
     const auto& gradient =
         std::get<CSSLinearGradientFunction>(cssBackgroundImage);

diff --git a/packages/react-native/ReactCommon/react/renderer/css/CSSBackgroundImage.h b/packages/react-native/ReactCommon/react/renderer/css/CSSBackgroundImage.h
@@ -845,11 +845,55 @@ struct CSSDataTypeParser<CSSLinearGradientFunction> {
 
 static_assert(CSSDataType<CSSLinearGradientFunction>);
 
+struct CSSURLFunction {
+  std::string url{};
+
+  bool operator==(const CSSURLFunction &rhs) const = default;
+};
+
+template <>
+struct CSSDataTypeParser<CSSURLFunction> {
+  static auto consumeFunctionBlock(const CSSFunctionBlock &func, CSSSyntaxParser &parser)
+      -> std::optional<CSSURLFunction>
+  {
+    if (!iequals(func.name, "url")) {
+      return {};
+    }
+
+    parser.consumeWhitespace();
+    std::string url;
+    while (auto token = parser.consumeComponentValue<std::optional<std::string>>(
+               [](const CSSPreservedToken &t) -> std::optional<std::string> {
+                 return std::string(t.stringValue());
+               })) {
+      if (!token->empty()) {
+        url += *token;
+      }
+    }
+
+    if (url.size() >= 2) {
+      char first = url.front();
+      char last = url.back();
+      if ((first == '"' && last == '"') || (first == '\'' && last == '\'')) {
+        url = url.substr(1, url.size() - 2);
+      }
+    }
+
+    if (!url.empty()) {
+      return CSSURLFunction{url};
+    }
+
+    return {};
+  }
+};
+
+static_assert(CSSDataType<CSSURLFunction>);
+
 /**
  * Representation of <background-image>
  * https://www.w3.org/TR/css-backgrounds-3/#background-image
  */
-using CSSBackgroundImage = CSSCompoundDataType<CSSLinearGradientFunction, CSSRadialGradientFunction>;
+using CSSBackgroundImage = CSSCompoundDataType<CSSLinearGradientFunction, CSSRadialGradientFunction, CSSURLFunction>;
 
 /**
  * Variant of possible CSS background image types