Add Android support for alpha modifier in PlatformColor

EvanBacon · EvanBacon · commit fb14f610fcb6 · 2026-01-01T11:03:31.000-08:00
This update enables the use of the alpha modifier for PlatformColor on Android by normalizing color specs to include alpha and updating the native bridge to apply alpha values. The rn-tester example is updated to demonstrate alpha usage on both iOS and Android, and documentation is clarified to reflect cross-platform support.
diff --git a/packages/react-native/Libraries/StyleSheet/PlatformColorValueTypes.android.js b/packages/react-native/Libraries/StyleSheet/PlatformColorValueTypes.android.js
@@ -26,28 +26,37 @@ export type PlatformColorOptions = {
 
 export type PlatformColorSpec = string | PlatformColorOptions;
 
+type AndroidColorSpec = {
+  name: string,
+  alpha?: number,
+};
+
 /** The actual type of the opaque NativeColorValue on Android platform */
 type LocalNativeColorValue = {
-  resource_paths?: Array<string>,
+  resource_paths?: Array<AndroidColorSpec>,
 };
 
 /**
- * Extracts color name from a spec (string or options object).
- * On Android, only the name is used - modifiers like alpha/prominence are iOS-specific.
+ * Normalizes a color spec (string or options object) to Android color spec format.
+ * On Android, only name and alpha are supported - prominence/contentHeadroom are iOS-specific.
  */
-function getColorName(spec: PlatformColorSpec): string {
+function normalizeColorSpec(spec: PlatformColorSpec): AndroidColorSpec {
   if (typeof spec === 'string') {
-    return spec;
+    return {name: spec};
+  }
+  const result: AndroidColorSpec = {name: spec.name};
+  if (spec.alpha != null) {
+    result.alpha = spec.alpha;
   }
-  return spec.name;
+  return result;
 }
 
 export const PlatformColor = (
   ...specs: Array<PlatformColorSpec>
 ): NativeColorValue => {
-  const names = specs.map(getColorName);
+  const normalizedSpecs = specs.map(normalizeColorSpec);
   // $FlowExpectedError[incompatible-return] LocalNativeColorValue is compatible with NativeColorValue
-  return {resource_paths: names};
+  return {resource_paths: normalizedSpecs};
 };
 
 export const normalizeColorObject = (
diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/bridge/ColorPropConverter.kt b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/bridge/ColorPropConverter.kt
@@ -23,13 +23,20 @@ public object ColorPropConverter {
   private fun supportWideGamut(): Boolean = Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
 
   private const val JSON_KEY = "resource_paths"
+  private const val JSON_KEY_NAME = "name"
+  private const val JSON_KEY_ALPHA = "alpha"
   private const val PREFIX_RESOURCE = "@"
   private const val PREFIX_ATTR = "?"
   private const val PACKAGE_DELIMITER = ":"
   private const val PATH_DELIMITER = "/"
   private const val ATTR = "attr"
   private const val ATTR_SEGMENT = "attr/"
 
+  private fun applyAlpha(color: Int, alpha: Double): Int {
+    val a = (alpha * 255).toInt().coerceIn(0, 255)
+    return (color and 0x00FFFFFF) or (a shl 24)
+  }
+
   private fun getColorInteger(value: Any?, context: Context): Int? {
     if (value == null) {
       return null
@@ -54,13 +61,30 @@ public object ColorPropConverter {
       val resourcePaths =
           value.getArray(JSON_KEY)
               ?: throw JSApplicationCausedNativeException(
-                  "ColorValue: The `$JSON_KEY` must be an array of color resource path strings."
+                  "ColorValue: The `$JSON_KEY` must be an array of color resource path strings or objects."
               )
 
       for (i in 0 until resourcePaths.size()) {
-        val result = resolveResourcePath(context, resourcePaths.getString(i))
+        val item = resourcePaths.getDynamic(i)
+        val resourcePath: String?
+        val alpha: Double?
+
+        when (item.type) {
+          ReadableType.String -> {
+            resourcePath = item.asString()
+            alpha = null
+          }
+          ReadableType.Map -> {
+            val map = item.asMap()
+            resourcePath = map.getString(JSON_KEY_NAME)
+            alpha = if (map.hasKey(JSON_KEY_ALPHA)) map.getDouble(JSON_KEY_ALPHA) else null
+          }
+          else -> continue
+        }
+
+        val result = resolveResourcePath(context, resourcePath)
         if (result != null) {
-          return result
+          return if (alpha != null) applyAlpha(result, alpha) else result
         }
       }
 
@@ -103,13 +127,31 @@ public object ColorPropConverter {
       val resourcePaths =
           value.getArray(JSON_KEY)
               ?: throw JSApplicationCausedNativeException(
-                  "ColorValue: The `$JSON_KEY` must be an array of color resource path strings."
+                  "ColorValue: The `$JSON_KEY` must be an array of color resource path strings or objects."
               )
 
       for (i in 0 until resourcePaths.size()) {
-        val result = resolveResourcePath(context, resourcePaths.getString(i))
+        val item = resourcePaths.getDynamic(i)
+        val resourcePath: String?
+        val alpha: Double?
+
+        when (item.type) {
+          ReadableType.String -> {
+            resourcePath = item.asString()
+            alpha = null
+          }
+          ReadableType.Map -> {
+            val map = item.asMap()
+            resourcePath = map.getString(JSON_KEY_NAME)
+            alpha = if (map.hasKey(JSON_KEY_ALPHA)) map.getDouble(JSON_KEY_ALPHA) else null
+          }
+          else -> continue
+        }
+
+        val result = resolveResourcePath(context, resourcePath)
         if (supportWideGamut() && result != null) {
-          return Color.valueOf(result)
+          val colorWithAlpha = if (alpha != null) applyAlpha(result, alpha) else result
+          return Color.valueOf(colorWithAlpha)
         }
       }
 
diff --git a/packages/rn-tester/js/examples/PlatformColor/PlatformColorExample.js b/packages/rn-tester/js/examples/PlatformColor/PlatformColorExample.js
@@ -185,39 +185,62 @@ function PlatformColorsExample() {
 }
 
 function AlphaColorsExample() {
-  if (Platform.OS !== 'ios') {
-    return (
-      <RNTesterText style={styles.labelCell}>
-        Alpha modifier is iOS-specific (no-op on other platforms)
-      </RNTesterText>
-    );
-  }
+  let colors: Array<{
+    color: ReturnType<typeof PlatformColor>,
+    label: string,
+  }> = [];
 
-  const colors = [
-    {label: 'systemBlue', color: PlatformColor('systemBlue')},
-    {
-      label: '{name: systemBlue, alpha: 0.75}',
-      color: PlatformColor({name: 'systemBlue', alpha: 0.75}),
-    },
-    {
-      label: '{name: systemBlue, alpha: 0.5}',
-      color: PlatformColor({name: 'systemBlue', alpha: 0.5}),
-    },
-    {
-      label: '{name: systemBlue, alpha: 0.25}',
-      color: PlatformColor({name: 'systemBlue', alpha: 0.25}),
-    },
-    {label: 'systemRed', color: PlatformColor('systemRed')},
-    {
-      label: '{name: systemRed, alpha: 0.5}',
-      color: PlatformColor({name: 'systemRed', alpha: 0.5}),
-    },
-    {label: 'label', color: PlatformColor('label')},
-    {
-      label: '{name: label, alpha: 0.5}',
-      color: PlatformColor({name: 'label', alpha: 0.5}),
-    },
-  ];
+  if (Platform.OS === 'ios') {
+    colors = [
+      {label: 'systemBlue', color: PlatformColor('systemBlue')},
+      {
+        label: '{name: systemBlue, alpha: 0.75}',
+        color: PlatformColor({name: 'systemBlue', alpha: 0.75}),
+      },
+      {
+        label: '{name: systemBlue, alpha: 0.5}',
+        color: PlatformColor({name: 'systemBlue', alpha: 0.5}),
+      },
+      {
+        label: '{name: systemBlue, alpha: 0.25}',
+        color: PlatformColor({name: 'systemBlue', alpha: 0.25}),
+      },
+      {label: 'systemRed', color: PlatformColor('systemRed')},
+      {
+        label: '{name: systemRed, alpha: 0.5}',
+        color: PlatformColor({name: 'systemRed', alpha: 0.5}),
+      },
+      {label: 'label', color: PlatformColor('label')},
+      {
+        label: '{name: label, alpha: 0.5}',
+        color: PlatformColor({name: 'label', alpha: 0.5}),
+      },
+    ];
+  } else if (Platform.OS === 'android') {
+    colors = [
+      {label: '?attr/colorPrimary', color: PlatformColor('?attr/colorPrimary')},
+      {
+        label: '{name: ?attr/colorPrimary, alpha: 0.75}',
+        color: PlatformColor({name: '?attr/colorPrimary', alpha: 0.75}),
+      },
+      {
+        label: '{name: ?attr/colorPrimary, alpha: 0.5}',
+        color: PlatformColor({name: '?attr/colorPrimary', alpha: 0.5}),
+      },
+      {
+        label: '{name: ?attr/colorPrimary, alpha: 0.25}',
+        color: PlatformColor({name: '?attr/colorPrimary', alpha: 0.25}),
+      },
+      {
+        label: '?attr/colorAccent',
+        color: PlatformColor('?attr/colorAccent'),
+      },
+      {
+        label: '{name: ?attr/colorAccent, alpha: 0.5}',
+        color: PlatformColor({name: '?attr/colorAccent', alpha: 0.5}),
+      },
+    ];
+  }
 
   return <ColorTable colors={colors} />;
 }
@@ -553,22 +576,22 @@ exports.examples = [
     },
   },
   {
-    title: 'Alpha Modifier (iOS)',
-    description: 'Use .alpha() to set the opacity of a platform color',
+    title: 'Alpha Modifier',
+    description: 'Use alpha option to set the opacity of a platform color',
     render(): React.MixedElement {
       return <AlphaColorsExample />;
     },
   },
   {
     title: 'Prominence Modifier (iOS 18+)',
-    description: 'Use .prominence() to set the visual prominence level',
+    description: 'Use prominence option to set the visual prominence level',
     render(): React.MixedElement {
       return <ProminenceColorsExample />;
     },
   },
   {
     title: 'Content Headroom (iOS 26+)',
-    description: 'Use .contentHeadroom() for HDR color brightness',
+    description: 'Use contentHeadroom option for HDR color brightness',
     render(): React.MixedElement {
       return <ContentHeadroomColorsExample />;
     },
