Add Android text font variation settings (#57804)

Summary:

Add a `fontVariationSettings` text style prop and carry it through Fabric text attributes into Android text rendering. Android now deserializes the prop for `<Text>`, applies it to `Paint`, and includes it in text measurement cache identity because variable axes can affect layout.

Preserve the distinction between an absent setting and an explicitly empty setting so nested text can inherit or clear the parent variation axes. Apply high-level font properties before low-level variation settings so explicit axes take precedence, matching CSS font realization order.

Settings syntax is intentionally forwarded unchanged through common text attributes and validated only by the Android font variation parser. This avoids narrowing the grammar Android accepts. As a result, malformed child settings are outside the supported inheritance contract: they replace an inherited value before Android validation and are not guaranteed to fall back to the parent settings. Android also accepts `normal` and the React Native empty-string convention as explicit resets.

Changelog:
[Android][Added] - Add `fontVariationSettings` support for `<Text>`

Reviewed By: Abbondanzo

Differential Revision: D113580491

Author: evankatz14

packages/react-native/Libraries/Components/View/ReactNativeStyleAttributes.js

@@ -258,6 +258,7 @@ const ReactNativeStyleAttributes: {[string]: AnyAttributeType, ...} = {
   fontSize: true,
   fontStyle: true,
   fontVariant: fontVariantAttribute,
+  fontVariationSettings: true,
   fontWeight: true,
   includeFontPadding: true,
   letterSpacing: true,

packages/react-native/Libraries/StyleSheet/StyleSheetTypes.d.ts

@@ -601,6 +601,12 @@ export interface TextStyle extends TextStyleIOS, TextStyleAndroid, ViewStyle {
     | 'heavy'
     | 'black'
     | undefined;
+  /**
+   * Specifies OpenType font variation axis values using CSS syntax. An empty
+   * string resets inherited variation settings. On Android, this requires API
+   * level 26 or later.
+   */
+  fontVariationSettings?: string | undefined;
   letterSpacing?: number | undefined;
   lineHeight?: number | undefined;
   textAlign?:

packages/react-native/Libraries/StyleSheet/StyleSheetTypes.js

@@ -1011,6 +1011,12 @@ type ____TextStyle_InternalBase = Readonly<{
    */
   fontWeight?: ____FontWeight_Internal,
   fontVariant?: ____FontVariantArray_Internal | string,
+  /**
+   * Specifies OpenType font variation axis values using CSS syntax. An empty
+   * string resets inherited variation settings. On Android, this requires API
+   * level 26 or later.
+   */
+  fontVariationSettings?: string,
   textShadowOffset?: Readonly<{
     width: number,
     height: number,

packages/react-native/ReactAndroid/api/ReactAndroid.api

@@ -4543,6 +4543,7 @@ public final class com/facebook/react/uimanager/ViewProps {
 	public static final field FONT_SIZE Ljava/lang/String;
 	public static final field FONT_STYLE Ljava/lang/String;
 	public static final field FONT_VARIANT Ljava/lang/String;
+	public static final field FONT_VARIATION_SETTINGS Ljava/lang/String;
 	public static final field FONT_WEIGHT Ljava/lang/String;
 	public static final field FOREGROUND_COLOR Ljava/lang/String;
 	public static final field GAP Ljava/lang/String;
@@ -6137,6 +6138,7 @@ public final class com/facebook/react/views/text/TextAttributeProps {
 	public static final field TA_KEY_FONT_SIZE_MULTIPLIER I
 	public static final field TA_KEY_FONT_STYLE I
 	public static final field TA_KEY_FONT_VARIANT I
+	public static final field TA_KEY_FONT_VARIATION_SETTINGS I
 	public static final field TA_KEY_FONT_WEIGHT I
 	public static final field TA_KEY_FOREGROUND_COLOR I
 	public static final field TA_KEY_IS_HIGHLIGHTED I
@@ -6167,6 +6169,7 @@ public final class com/facebook/react/views/text/TextAttributeProps {
 	public final fun getFontFeatureSettings ()Ljava/lang/String;
 	public final fun getFontSize ()I
 	public final fun getFontStyle ()I
+	public final fun getFontVariationSettings ()Ljava/lang/String;
 	public final fun getFontWeight ()I
 	public final fun getLayoutDirection ()I
 	public final fun getLetterSpacing ()F

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/ViewProps.kt

@@ -84,6 +84,7 @@ public object ViewProps {
   public const val FONT_WEIGHT: String = "fontWeight"
   public const val FONT_STYLE: String = "fontStyle"
   public const val FONT_VARIANT: String = "fontVariant"
+  public const val FONT_VARIATION_SETTINGS: String = "fontVariationSettings"
   public const val FONT_FAMILY: String = "fontFamily"
   public const val LINE_HEIGHT: String = "lineHeight"
   public const val LETTER_SPACING: String = "letterSpacing"

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/text/ReactTypefaceUtils.kt

@@ -10,8 +10,11 @@ package com.facebook.react.views.text
 import android.content.Context
 import android.content.res.AssetManager
 import android.content.res.Configuration
+import android.graphics.Paint
 import android.graphics.Typeface
+import android.graphics.fonts.FontVariationAxis
 import android.os.Build
+import com.facebook.common.logging.FLog
 import com.facebook.react.bridge.ReadableArray
 import com.facebook.react.common.ReactConstants
 import com.facebook.react.common.assets.ReactFontManager
@@ -151,4 +154,44 @@ public object ReactTypefaceUtils {
 
     return Typeface.create(baseTypeface, adjustedWeight, italic)
   }
+
+  internal fun parseFontVariationSettings(fontVariationSettings: String?): String? {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+      return null
+    }
+
+    if (fontVariationSettings.isNullOrEmpty()) {
+      return fontVariationSettings
+    }
+
+    if (fontVariationSettings.trim().equals("normal", ignoreCase = true)) {
+      return ""
+    }
+
+    return try {
+      FontVariationAxis.fromFontVariationSettings(fontVariationSettings)
+      fontVariationSettings
+    } catch (exception: IllegalArgumentException) {
+      FLog.w(ReactConstants.TAG, "Invalid fontVariationSettings: $fontVariationSettings")
+      null
+    }
+  }
+
+  internal fun applyFontVariationSettings(paint: Paint, fontVariationSettings: String?) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+      return
+    }
+
+    try {
+      paint.setFontVariationSettings(fontVariationSettings)
+    } catch (exception: IllegalArgumentException) {
+      // Paint instances are reused, so explicitly clear axes from a previous layout.
+      paint.setFontVariationSettings(null)
+      FLog.w(
+          ReactConstants.TAG,
+          "Invalid fontVariationSettings: $fontVariationSettings",
+          exception,
+      )
+    }
+  }
 }

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/text/TextAttributeProps.kt

@@ -25,6 +25,7 @@ import com.facebook.react.uimanager.ReactStylesDiffMap
 import com.facebook.react.uimanager.ViewProps
 import com.facebook.react.views.text.ReactTypefaceUtils.parseFontStyle
 import com.facebook.react.views.text.ReactTypefaceUtils.parseFontVariant
+import com.facebook.react.views.text.ReactTypefaceUtils.parseFontVariationSettings
 import com.facebook.react.views.text.ReactTypefaceUtils.parseFontWeight
 import kotlin.math.ceil
 
@@ -153,6 +154,10 @@ public class TextAttributeProps private constructor() {
   public var fontFeatureSettings: String? = null
     private set
 
+  /** @see android.graphics.Paint.setFontVariationSettings */
+  public var fontVariationSettings: String? = null
+    private set
+
   @Deprecated("Use lineHeight instead", ReplaceWith("lineHeight"))
   public val effectiveLineHeight: Float
     get() = lineHeight
@@ -396,6 +401,7 @@ public class TextAttributeProps private constructor() {
     public const val TA_KEY_TEXT_TRANSFORM: Int = 27
     public const val TA_KEY_MAX_FONT_SIZE_MULTIPLIER: Int = 29
     public const val TA_KEY_TEXT_EFFECTS: Int = 30
+    public const val TA_KEY_FONT_VARIATION_SETTINGS: Int = 31
     private const val TE_KEY_NAME: Int = 0
     private const val TE_KEY_PROPS: Int = 1
 
@@ -433,6 +439,8 @@ public class TextAttributeProps private constructor() {
           TA_KEY_FONT_WEIGHT -> result.setFontWeight(entry.stringValue)
           TA_KEY_FONT_STYLE -> result.setFontStyle(entry.stringValue)
           TA_KEY_FONT_VARIANT -> result.setFontVariant(entry.mapBufferValue)
+          TA_KEY_FONT_VARIATION_SETTINGS ->
+              result.fontVariationSettings = parseFontVariationSettings(entry.stringValue)
           TA_KEY_ALLOW_FONT_SCALING -> result.allowFontScaling = entry.booleanValue
           TA_KEY_LETTER_SPACING -> result.letterSpacing = entry.doubleValue.toFloat()
           TA_KEY_LINE_HEIGHT -> result.lineHeight = entry.doubleValue.toFloat()
@@ -500,6 +508,8 @@ public class TextAttributeProps private constructor() {
       result.setFontWeight(getStringProp(props, ViewProps.FONT_WEIGHT))
       result.setFontStyle(getStringProp(props, ViewProps.FONT_STYLE))
       result.setFontVariant(getArrayProp(props, ViewProps.FONT_VARIANT))
+      result.fontVariationSettings =
+          parseFontVariationSettings(getStringProp(props, ViewProps.FONT_VARIATION_SETTINGS))
       result.includeFontPadding = getBooleanProp(props, ViewProps.INCLUDE_FONT_PADDING, true)
       result.setTextDecorationLine(getStringProp(props, ViewProps.TEXT_DECORATION_LINE))
       result.textDecorationColor =

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/text/TextLayoutManager.kt

@@ -313,6 +313,7 @@ internal object TextLayoutManager {
         if (
             textAttributes.fontStyle != ReactConstants.UNSET ||
                 textAttributes.fontWeight != ReactConstants.UNSET ||
+                textAttributes.fontVariationSettings != null ||
                 textAttributes.fontFamily != null
         ) {
           ops.add(
@@ -323,6 +324,7 @@ internal object TextLayoutManager {
                       textAttributes.fontStyle,
                       textAttributes.fontWeight,
                       textAttributes.fontFeatureSettings,
+                      textAttributes.fontVariationSettings,
                       textAttributes.fontFamily,
                       assets,
                       fontWeightAdjustment,
@@ -547,13 +549,15 @@ internal object TextLayoutManager {
         if (
             fragment.props.fontStyle != ReactConstants.UNSET ||
                 fragment.props.fontWeight != ReactConstants.UNSET ||
+                fragment.props.fontVariationSettings != null ||
                 fragment.props.fontFamily != null
         ) {
           spannable.setSpan(
               CustomStyleSpan(
                   fragment.props.fontStyle,
                   fragment.props.fontWeight,
                   fragment.props.fontFeatureSettings,
+                  fragment.props.fontVariationSettings,
                   fragment.props.fontFamily,
                   assets,
                   fontWeightAdjustment,
@@ -883,6 +887,7 @@ internal object TextLayoutManager {
     if (
         baseTextAttributes.fontStyle != ReactConstants.UNSET ||
             baseTextAttributes.fontWeight != ReactConstants.UNSET ||
+            baseTextAttributes.fontVariationSettings != null ||
             baseTextAttributes.fontFamily != null
     ) {
       val typeface =
@@ -912,6 +917,8 @@ internal object TextLayoutManager {
         paint.setTypeface(typeface)
       }
     }
+
+    ReactTypefaceUtils.applyFontVariationSettings(paint, baseTextAttributes.fontVariationSettings)
   }
 
   /**

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/text/internal/span/CustomStyleSpan.kt

@@ -31,6 +31,7 @@ internal class CustomStyleSpan(
     private val privateStyle: Int,
     private val privateWeight: Int,
     val fontFeatureSettings: String?,
+    val fontVariationSettings: String?,
     val fontFamily: String?,
     private val assetManager: AssetManager,
     private val fontWeightAdjustment: Int = 0,
@@ -41,6 +42,7 @@ internal class CustomStyleSpan(
         privateStyle,
         privateWeight,
         fontFeatureSettings,
+        fontVariationSettings,
         fontFamily,
         assetManager,
         fontWeightAdjustment,
@@ -53,6 +55,7 @@ internal class CustomStyleSpan(
         privateStyle,
         privateWeight,
         fontFeatureSettings,
+        fontVariationSettings,
         fontFamily,
         assetManager,
         fontWeightAdjustment,
@@ -81,6 +84,7 @@ internal class CustomStyleSpan(
         style: Int,
         weight: Int,
         fontFeatureSettingsParam: String?,
+        fontVariationSettingsParam: String?,
         family: String?,
         assetManager: AssetManager,
         fontWeightAdjustment: Int,
@@ -92,6 +96,7 @@ internal class CustomStyleSpan(
       paint.apply {
         fontFeatureSettings = fontFeatureSettingsParam
         setTypeface(adjustedTypeface)
+        ReactTypefaceUtils.applyFontVariationSettings(this, fontVariationSettingsParam)
         isSubpixelText = true
         isLinearText = true
       }

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/textinput/ReactEditText.kt

@@ -826,7 +826,8 @@ public open class ReactEditText public constructor(context: Context) : AppCompat
       span.style == fontStyle &&
           span.fontFamily == fontFamily &&
           span.weight == fontWeight &&
-          span.fontFeatureSettings == fontFeatureSettings
+          span.fontFeatureSettings == fontFeatureSettings &&
+          span.fontVariationSettings == null
     }
   }
 
@@ -908,6 +909,7 @@ public open class ReactEditText public constructor(context: Context) : AppCompat
               fontStyle,
               fontWeight,
               fontFeatureSettings,
+              null,
               fontFamily,
               context.assets,
               getFontWeightAdjustment(context),