From 7e7d726ab9d1c355e9365f3af8820b54bd32b231 Mon Sep 17 00:00:00 2001 From: Ahmed Sbai Date: Sun, 9 Aug 2026 21:26:26 +0200 Subject: [PATCH] Document Android 14+ non-linear font scaling on getFontScale and allowFontScaling On Android 14 and newer, the OS scales fonts non-linearly (small sizes grow by the full factor, large sizes progressively less; 30sp is pinned until the setting exceeds 1.5), so PixelRatio.getFontScale() no longer predicts rendered text sizes. Document this on the PixelRatio and Text pages for next and 0.86. Prompted by facebook/react-native#56961, where the non-linear curve was mistaken for a rendering bug. --- docs/pixelratio.md | 4 + docs/text.md | 2 + .../versioned_docs/version-0.86/pixelratio.md | 4 + website/versioned_docs/version-0.86/text.md | 1562 +++++++++-------- 4 files changed, 792 insertions(+), 780 deletions(-) diff --git a/docs/pixelratio.md b/docs/pixelratio.md index f298a8e73ab..61d560dd38b 100644 --- a/docs/pixelratio.md +++ b/docs/pixelratio.md @@ -149,6 +149,10 @@ Returns the scaling factor for font sizes. This is the ratio that is used to cal If a font scale is not set, this returns the device pixel ratio. +:::note +On Android 14 and newer, the system scales fonts [non-linearly](https://developer.android.com/about/versions/14/features#non-linear-font-scaling) once the user's font scale is 1.05 or higher: small fonts grow by roughly the full factor, while larger fonts grow progressively less (for example, a 30sp font does not grow at all until the setting exceeds 1.5). `getFontScale()` still returns the linear preference value (such as `1.3`), so multiplying a font size by it will overestimate the rendered size of large text on these devices. +::: + --- ### `getPixelSizeForLayoutSize()` diff --git a/docs/text.md b/docs/text.md index b637552bfa5..33b4ee15b56 100644 --- a/docs/text.md +++ b/docs/text.md @@ -312,6 +312,8 @@ Specifies whether fonts should be scaled down automatically to fit given style c Specifies whether fonts should scale to respect Text Size accessibility settings. +On Android 14 and newer, scaling is [non-linear](https://developer.android.com/about/versions/14/features#non-linear-font-scaling): as the user's font scale setting grows, large fonts are scaled up less than small ones. + | Type | Default | | ------- | ------- | | boolean | `true` | diff --git a/website/versioned_docs/version-0.86/pixelratio.md b/website/versioned_docs/version-0.86/pixelratio.md index f298a8e73ab..61d560dd38b 100644 --- a/website/versioned_docs/version-0.86/pixelratio.md +++ b/website/versioned_docs/version-0.86/pixelratio.md @@ -149,6 +149,10 @@ Returns the scaling factor for font sizes. This is the ratio that is used to cal If a font scale is not set, this returns the device pixel ratio. +:::note +On Android 14 and newer, the system scales fonts [non-linearly](https://developer.android.com/about/versions/14/features#non-linear-font-scaling) once the user's font scale is 1.05 or higher: small fonts grow by roughly the full factor, while larger fonts grow progressively less (for example, a 30sp font does not grow at all until the setting exceeds 1.5). `getFontScale()` still returns the linear preference value (such as `1.3`), so multiplying a font size by it will overestimate the rendered size of large text on these devices. +::: + --- ### `getPixelSizeForLayoutSize()` diff --git a/website/versioned_docs/version-0.86/text.md b/website/versioned_docs/version-0.86/text.md index 0e72ec8c27b..33b4ee15b56 100644 --- a/website/versioned_docs/version-0.86/text.md +++ b/website/versioned_docs/version-0.86/text.md @@ -1,780 +1,782 @@ ---- -id: text -title: Text ---- - -A React component for displaying text. - -`Text` supports nesting, styling, and touch handling. - -In the following example, the nested title and body text will inherit the `fontFamily` from `styles.baseText`, but the title provides its own additional styles. The title and body will stack on top of each other on account of the literal newlines: - -```SnackPlayer name=Text%20Function%20Component%20Example -import {useState} from 'react'; -import {Text, StyleSheet} from 'react-native'; -import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context'; - -const TextInANest = () => { - const [titleText, setTitleText] = useState("Bird's Nest"); - const bodyText = 'This is not really a bird nest.'; - - const onPressTitle = () => { - setTitleText("Bird's Nest [pressed]"); - }; - - return ( - - - - - {titleText} - {'\n'} - {'\n'} - - {bodyText} - - - - ); -}; - -const styles = StyleSheet.create({ - container: { - flex: 1, - }, - baseText: { - fontFamily: 'Cochin', - }, - titleText: { - fontSize: 20, - fontWeight: 'bold', - }, -}); - -export default TextInANest; -``` - -## Nested text - -Both Android and iOS allow you to display formatted text by annotating ranges of a string with specific formatting like bold or colored text (`NSAttributedString` on iOS, `SpannableString` on Android). In practice, this is very tedious. For React Native, we decided to use the web paradigm for this, where you can nest text to achieve the same effect. - -```SnackPlayer name=Nested%20Text%20Example -import {Text, StyleSheet} from 'react-native'; -import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context'; - -const BoldAndBeautiful = () => ( - - - - I am bold - and red - - - -); - -const styles = StyleSheet.create({ - container: { - flex: 1, - }, - baseText: { - fontWeight: 'bold', - }, - innerText: { - color: 'red', - }, -}); - -export default BoldAndBeautiful; -``` - -Behind the scenes, React Native converts this to a flat `NSAttributedString` or `SpannableString` that contains the following information: - -``` -"I am bold and red" -0-9: bold -9-17: bold, red -``` - -## Containers - -The `` element is unique relative to layout: everything inside is no longer using the Flexbox layout but using text layout. This means that elements inside of a `` are no longer rectangles, but wrap when they see the end of the line. - -```tsx - - First part and - second part - -// Text container: the text will be inline, if the space allows it -// |First part and second part| - -// otherwise, the text will flow as if it was one -// |First part | -// |and second | -// |part | - - - First part and - second part - -// View container: each text is its own block -// |First part and| -// |second part | - -// otherwise, the text will flow in its own block -// |First part | -// |and | -// |second part| -``` - -## Limited Style Inheritance - -On the web, the usual way to set a font family and size for the entire document is to take advantage of inherited CSS properties like so: - -```css -html { - font-family: - 'lucida grande', tahoma, verdana, arial, sans-serif; - font-size: 11px; - color: #141823; -} -``` - -All elements in the document will inherit this font unless they or one of their parents specifies a new rule. - -In React Native, we are more strict about it: **you must wrap all the text nodes inside of a `` component**. You cannot have a text node directly under a ``. - -```tsx -// BAD: will raise exception, can't have a text node as child of a - - Some text - - -// GOOD - - - Some text - - -``` - -You also lose the ability to set up a default font for an entire subtree. Meanwhile, `fontFamily` only accepts a single font name, which is different from `font-family` in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component `MyAppText` that includes them and use this component across your app. You can also use this component to make more specific components like `MyAppHeaderText` for other kinds of text. - -```tsx - - - Text styled with the default font for the entire application - - Text styled as a header - -``` - -Assuming that `MyAppText` is a component that only renders out its children into a `Text` component with styling, then `MyAppHeaderText` can be defined as follows: - -```tsx -const MyAppHeaderText = ({children}) => { - return ( - - {children} - - ); -}; -``` - -Composing `MyAppText` in this way ensures that we get the styles from a top-level component, but leaves us the ability to add/override them in specific use cases. - -React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red. - -```tsx - - I am bold - and red - -``` - -We believe that this more constrained way to style text will yield better apps: - -- (Developer) React components are designed with strong isolation in mind: You should be able to drop a component anywhere in your application, trusting that as long as the props are the same, it will look and behave the same way. Text properties that could inherit from outside of the props would break this isolation. - -- (Implementor) The implementation of React Native is also simplified. We do not need to have a `fontFamily` field on every single element, and we do not need to potentially traverse the tree up to the root every time we display a text node. The style inheritance is only encoded inside of the native Text component and doesn't leak to other components or the system itself. - ---- - -# Reference - -## Props - -### `accessibilityHint` - -An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label. - -| Type | -| ------ | -| string | - ---- - -### `accessibilityLanguage`
iOS
- -A value indicating which language should be used by the screen reader when the user interacts with the element. It should follow the [BCP 47 specification](https://www.rfc-editor.org/info/bcp47). - -See the [iOS `accessibilityLanguage` doc](https://developer.apple.com/documentation/objectivec/nsobject/1615192-accessibilitylanguage) for more information. - -| Type | -| ------ | -| string | - ---- - -### `accessibilityLabel` - -Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space. - -| Type | -| ------ | -| string | - ---- - -### `accessibilityRole` - -Tells the screen reader to treat the currently focused on element as having a specific role. - -On iOS, these roles map to corresponding Accessibility Traits. Image button has the same functionality as if the trait was set to both 'image' and 'button'. See the [Accessibility guide](accessibility.md#accessibilitytraits-ios) for more information. - -On Android, these roles have similar functionality on TalkBack as adding Accessibility Traits does on Voiceover in iOS - -| Type | -| ---------------------------------------------------- | -| [AccessibilityRole](accessibility#accessibilityrole) | - ---- - -### `accessibilityState` - -Tells the screen reader to treat the currently focused on element as being in a specific state. - -You can provide one state, no state, or multiple states. The states must be passed in through an object, e.g. `{selected: true, disabled: true}`. - -| Type | -| ------------------------------------------------------ | -| [AccessibilityState](accessibility#accessibilitystate) | - ---- - -### `accessibilityActions` - -Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The `accessibilityActions` property should contain a list of action objects. Each action object should contain the field name and label. - -See the [Accessibility guide](accessibility.md#accessibility-actions) for more information. - -| Type | Required | -| ----- | -------- | -| array | No | - ---- - -### `onAccessibilityAction` - -Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform. - -See the [Accessibility guide](accessibility.md#accessibility-actions) for more information. - -| Type | Required | -| -------- | -------- | -| function | No | - ---- - -### `accessible` - -When set to `true`, indicates that the view is an accessibility element. - -See the [Accessibility guide](accessibility#accessible-ios-android) for more information. - -| Type | Default | -| ------- | ------- | -| boolean | `true` | - ---- - -### `adjustsFontSizeToFit` - -Specifies whether fonts should be scaled down automatically to fit given style constraints. - -| Type | Default | -| ------- | ------- | -| boolean | `false` | - ---- - -### `allowFontScaling` - -Specifies whether fonts should scale to respect Text Size accessibility settings. - -| Type | Default | -| ------- | ------- | -| boolean | `true` | - ---- - -### `android_hyphenationFrequency`
Android
- -Sets the frequency of automatic hyphenation to use when determining word breaks on Android API Level 23+. - -| Type | Default | -| ----------------------------------- | -------- | -| enum(`'none'`, `'normal'`,`'full'`) | `'none'` | - ---- - -### `aria-busy` - -Indicates an element is being modified and that assistive technologies may want to wait until the changes are complete before informing the user about the update. - -| Type | Default | -| ------- | ------- | -| boolean | false | - ---- - -### `aria-checked` - -Indicates the state of a checkable element. This field can either take a boolean or the "mixed" string to represent mixed checkboxes. - -| Type | Default | -| ---------------- | ------- | -| boolean, 'mixed' | false | - ---- - -### `aria-disabled` - -Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. - -| Type | Default | -| ------- | ------- | -| boolean | false | - ---- - -### `aria-expanded` - -Indicates whether an expandable element is currently expanded or collapsed. - -| Type | Default | -| ------- | ------- | -| boolean | false | - ---- - -### `aria-label` - -Defines a string value that labels an interactive element. - -| Type | -| ------ | -| string | - ---- - -### `aria-selected` - -Indicates whether a selectable element is currently selected or not. - -| Type | -| ------- | -| boolean | - -### `dataDetectorType`
Android
- -Determines the types of data converted to clickable URLs in the text element. By default, no data types are detected. - -You can provide only one type. - -| Type | Default | -| ------------------------------------------------------------- | -------- | -| enum(`'phoneNumber'`, `'link'`, `'email'`, `'none'`, `'all'`) | `'none'` | - ---- - -### `disabled`
Android
- -Specifies the disabled state of the text view for testing purposes. - -| Type | Default | -| ---- | ------- | -| bool | `false` | - ---- - -### `dynamicTypeRamp`
iOS
- -The [Dynamic Type](https://developer.apple.com/documentation/uikit/uifont/scaling_fonts_automatically) ramp to apply to this element on iOS. - -| Type | Default | -| -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| enum(`'caption2'`, `'caption1'`, `'footnote'`, `'subheadline'`, `'callout'`, `'body'`, `'headline'`, `'title3'`, `'title2'`, `'title1'`, `'largeTitle'`) | `'body'` | - ---- - -### `ellipsizeMode` - -When `numberOfLines` is set, this prop defines how the text will be truncated. `numberOfLines` must be set in conjunction with this prop. - -This can be one of the following values: - -- `head` - The line is displayed so that the end fits in the container and the missing text at the beginning of the line is indicated by an ellipsis glyph. e.g., "...wxyz" -- `middle` - The line is displayed so that the beginning and end fit in the container and the missing text in the middle is indicated by an ellipsis glyph. "ab...yz" -- `tail` - The line is displayed so that the beginning fits in the container and the missing text at the end of the line is indicated by an ellipsis glyph. e.g., "abcd..." -- `clip` - Lines are not drawn past the edge of the text container. - -:::note -On Android, when `numberOfLines` is set to a value higher than `1`, only `tail` value will work correctly. -::: - -| Type | Default | -| ---------------------------------------------- | ------- | -| enum(`'head'`, `'middle'`, `'tail'`, `'clip'`) | `tail` | - ---- - -### `id` - -Used to locate this view from native code. Has precedence over `nativeID` prop. - -| Type | -| ------ | -| string | - ---- - -### `maxFontSizeMultiplier` - -Specifies the largest possible scale a font can reach when `allowFontScaling` is enabled. Possible values: - -- `null/undefined`: inherit from the parent node or the global default (0) -- `0`: no max, ignore parent/global default -- `>= 1`: sets the `maxFontSizeMultiplier` of this node to this value - -| Type | Default | -| ------ | ----------- | -| number | `undefined` | - ---- - -### `minimumFontScale` - -Specifies the smallest possible scale a font can reach when `adjustsFontSizeToFit` is enabled. (values 0.01-1.0). - -| Type | -| ------ | -| number | - ---- - -### `nativeID` - -Used to locate this view from native code. - -| Type | -| ------ | -| string | - ---- - -### `numberOfLines` - -Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number. Setting this property to `0` will result in unsetting this value, which means that no lines restriction will be applied. - -This prop is commonly used with `ellipsizeMode`. - -| Type | Default | -| ------ | ------- | -| number | `0` | - ---- - -### `onLayout` - -Invoked on mount and on layout changes. - -| Type | -| -------------------------------------------------------- | -| `md ({nativeEvent: [LayoutEvent](layoutevent)}) => void` | - ---- - -### `onLongPress` - -This function is called on long press. - -| Type | -| ------------------------------------------------------ | -| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | - ---- - -### `onMoveShouldSetResponder` - -Does this view want to "claim" touch responsiveness? This is called for every touch move on the `View` when it is not the responder. - -| Type | -| --------------------------------------------------------- | -| `md ({nativeEvent: [PressEvent](pressevent)}) => boolean` | - ---- - -### `onPress` - -Function called on user press, triggered after `onPressOut`. - -| Type | -| ------------------------------------------------------ | -| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | - ---- - -### `onPressIn` - -Called immediately when a touch is engaged, before `onPressOut` and `onPress`. - -| Type | -| ------------------------------------------------------ | -| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | - ---- - -### `onPressOut` - -Called when a touch is released. - -| Type | -| ------------------------------------------------------ | -| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | - ---- - -### `onResponderGrant` - -The View is now responding to touch events. This is the time to highlight and show the user what is happening. - -On Android, return true from this callback to prevent any other native components from becoming responder until this responder terminates. - -| Type | -| ----------------------------------------------------------------- | -| `md ({nativeEvent: [PressEvent](pressevent)}) => void ｜ boolean` | - ---- - -### `onResponderMove` - -The user is moving their finger. - -| Type | -| ------------------------------------------------------ | -| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | - ---- - -### `onResponderRelease` - -Fired at the end of the touch. - -| Type | -| ------------------------------------------------------ | -| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | - ---- - -### `onResponderTerminate` - -The responder has been taken from the `View`. Might be taken by other views after a call to `onResponderTerminationRequest`, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS) - -| Type | -| ------------------------------------------------------ | -| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | - ---- - -### `onResponderTerminationRequest` - -Some other `View` wants to become a responder and is asking this `View` to release its responder. Returning `true` allows its release. - -| Type | -| --------------------------------------------------------- | -| `md ({nativeEvent: [PressEvent](pressevent)}) => boolean` | - ---- - -### `onStartShouldSetResponderCapture` - -If a parent `View` wants to prevent a child `View` from becoming a responder on a touch start, it should have this handler which returns `true`. - -| Type | -| --------------------------------------------------------- | -| `md ({nativeEvent: [PressEvent](pressevent)}) => boolean` | - ---- - -### `onTextLayout` - -Invoked on Text layout change. - -| Type | -| ---------------------------------------------------- | -| ([`TextLayoutEvent`](text#textlayoutevent)) => mixed | - ---- - -### `pressRetentionOffset` - -When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations. - -| Type | -| -------------------- | -| [Rect](rect), number | - ---- - -### `ref` - -A ref setter that will be assigned an [element node](element-nodes) when mounted. - -Note that `Text` components don't provide text nodes, the same way that paragraph elements (`

`) on Web are element nodes instead of text nodes. Text nodes can be found as their child nodes instead. - ---- - -### `role` - -`role` communicates the purpose of a component to the user of an assistive technology. Has precedence over the [`accessibilityRole`](text#accessibilityrole) prop. - -| Type | -| -------------------------- | -| [Role](accessibility#role) | - ---- - -### `selectable` - -Lets the user select text, to use the native copy and paste functionality. - -| Type | Default | -| ------- | ------- | -| boolean | `false` | - ---- - -### `selectionColor`

Android
- -The highlight color of the text. - -| Type | -| --------------- | -| [color](colors) | - ---- - -### `style` - -| Type | -| -------------------------------------------------------------------- | -| [Text Style](text-style-props), [View Style Props](view-style-props) | - ---- - -### `suppressHighlighting`
iOS
- -When `true`, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down. - -| Type | Default | -| ------- | ------- | -| boolean | `false` | - ---- - -### `testID` - -Used to locate this view in end-to-end tests. - -| Type | -| ------ | -| string | - ---- - -### `textBreakStrategy`
Android
- -Set text break strategy on Android API Level 23+, possible values are `simple`, `highQuality`, `balanced`. - -| Type | Default | -| ----------------------------------------------- | ------------- | -| enum(`'simple'`, `'highQuality'`, `'balanced'`) | `highQuality` | - ---- - -### `lineBreakStrategyIOS`
iOS
- -Set line break strategy on iOS 14+. Possible values are `none`, `standard`, `hangul-word` and `push-out`. - -| Type | Default | -| ----------------------------------------------------------- | -------- | -| enum(`'none'`, `'standard'`, `'hangul-word'`, `'push-out'`) | `'none'` | - -## Type Definitions - -### TextLayout - -`TextLayout` object is a part of [`TextLayoutEvent`](text#textlayoutevent) callback and contains the measurement data for `Text` line. - -#### Example - -```js -{ - capHeight: 10.496, - ascender: 14.624, - descender: 4, - width: 28.224, - height: 18.624, - xHeight: 6.048, - x: 0, - y: 0 -} -``` - -#### Properties - -| Name | Type | Optional | Description | -| --------- | ------ | -------- | ------------------------------------------------------------------- | -| ascender | number | No | The line ascender height after the text layout changes. | -| capHeight | number | No | Height of capital letter above the baseline. | -| descender | number | No | The line descender height after the text layout changes. | -| height | number | No | Height of the line after the text layout changes. | -| width | number | No | Width of the line after the text layout changes. | -| x | number | No | Line X coordinate inside the Text component. | -| xHeight | number | No | Distance between the baseline and median of the line (corpus size). | -| y | number | No | Line Y coordinate inside the Text component. | - -### TextLayoutEvent - -`TextLayoutEvent` object is returned in the callback as a result of a component layout change. It contains a key called `lines` with a value which is an array containing [`TextLayout`](text#textlayout) object corresponded to every rendered text line. - -#### Example - -```js -{ - lines: [ - TextLayout, - TextLayout, - // ... - ]; - target: 1127; -} -``` - -#### Properties - -| Name | Type | Optional | Description | -| ------ | --------------------------------------- | -------- | ----------------------------------------------------- | -| lines | array of [TextLayout](text#textlayout)s | No | Provides the TextLayout data for every rendered line. | -| target | number | No | The node id of the element. | +--- +id: text +title: Text +--- + +A React component for displaying text. + +`Text` supports nesting, styling, and touch handling. + +In the following example, the nested title and body text will inherit the `fontFamily` from `styles.baseText`, but the title provides its own additional styles. The title and body will stack on top of each other on account of the literal newlines: + +```SnackPlayer name=Text%20Function%20Component%20Example +import {useState} from 'react'; +import {Text, StyleSheet} from 'react-native'; +import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context'; + +const TextInANest = () => { + const [titleText, setTitleText] = useState("Bird's Nest"); + const bodyText = 'This is not really a bird nest.'; + + const onPressTitle = () => { + setTitleText("Bird's Nest [pressed]"); + }; + + return ( + + + + + {titleText} + {'\n'} + {'\n'} + + {bodyText} + + + + ); +}; + +const styles = StyleSheet.create({ + container: { + flex: 1, + }, + baseText: { + fontFamily: 'Cochin', + }, + titleText: { + fontSize: 20, + fontWeight: 'bold', + }, +}); + +export default TextInANest; +``` + +## Nested text + +Both Android and iOS allow you to display formatted text by annotating ranges of a string with specific formatting like bold or colored text (`NSAttributedString` on iOS, `SpannableString` on Android). In practice, this is very tedious. For React Native, we decided to use the web paradigm for this, where you can nest text to achieve the same effect. + +```SnackPlayer name=Nested%20Text%20Example +import {Text, StyleSheet} from 'react-native'; +import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context'; + +const BoldAndBeautiful = () => ( + + + + I am bold + and red + + + +); + +const styles = StyleSheet.create({ + container: { + flex: 1, + }, + baseText: { + fontWeight: 'bold', + }, + innerText: { + color: 'red', + }, +}); + +export default BoldAndBeautiful; +``` + +Behind the scenes, React Native converts this to a flat `NSAttributedString` or `SpannableString` that contains the following information: + +``` +"I am bold and red" +0-9: bold +9-17: bold, red +``` + +## Containers + +The `` element is unique relative to layout: everything inside is no longer using the Flexbox layout but using text layout. This means that elements inside of a `` are no longer rectangles, but wrap when they see the end of the line. + +```tsx + + First part and + second part + +// Text container: the text will be inline, if the space allows it +// |First part and second part| + +// otherwise, the text will flow as if it was one +// |First part | +// |and second | +// |part | + + + First part and + second part + +// View container: each text is its own block +// |First part and| +// |second part | + +// otherwise, the text will flow in its own block +// |First part | +// |and | +// |second part| +``` + +## Limited Style Inheritance + +On the web, the usual way to set a font family and size for the entire document is to take advantage of inherited CSS properties like so: + +```css +html { + font-family: + 'lucida grande', tahoma, verdana, arial, sans-serif; + font-size: 11px; + color: #141823; +} +``` + +All elements in the document will inherit this font unless they or one of their parents specifies a new rule. + +In React Native, we are more strict about it: **you must wrap all the text nodes inside of a `` component**. You cannot have a text node directly under a ``. + +```tsx +// BAD: will raise exception, can't have a text node as child of a + + Some text + + +// GOOD + + + Some text + + +``` + +You also lose the ability to set up a default font for an entire subtree. Meanwhile, `fontFamily` only accepts a single font name, which is different from `font-family` in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component `MyAppText` that includes them and use this component across your app. You can also use this component to make more specific components like `MyAppHeaderText` for other kinds of text. + +```tsx + + + Text styled with the default font for the entire application + + Text styled as a header + +``` + +Assuming that `MyAppText` is a component that only renders out its children into a `Text` component with styling, then `MyAppHeaderText` can be defined as follows: + +```tsx +const MyAppHeaderText = ({children}) => { + return ( + + {children} + + ); +}; +``` + +Composing `MyAppText` in this way ensures that we get the styles from a top-level component, but leaves us the ability to add/override them in specific use cases. + +React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red. + +```tsx + + I am bold + and red + +``` + +We believe that this more constrained way to style text will yield better apps: + +- (Developer) React components are designed with strong isolation in mind: You should be able to drop a component anywhere in your application, trusting that as long as the props are the same, it will look and behave the same way. Text properties that could inherit from outside of the props would break this isolation. + +- (Implementor) The implementation of React Native is also simplified. We do not need to have a `fontFamily` field on every single element, and we do not need to potentially traverse the tree up to the root every time we display a text node. The style inheritance is only encoded inside of the native Text component and doesn't leak to other components or the system itself. + +--- + +# Reference + +## Props + +### `accessibilityHint` + +An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label. + +| Type | +| ------ | +| string | + +--- + +### `accessibilityLanguage`
iOS
+ +A value indicating which language should be used by the screen reader when the user interacts with the element. It should follow the [BCP 47 specification](https://www.rfc-editor.org/info/bcp47). + +See the [iOS `accessibilityLanguage` doc](https://developer.apple.com/documentation/objectivec/nsobject/1615192-accessibilitylanguage) for more information. + +| Type | +| ------ | +| string | + +--- + +### `accessibilityLabel` + +Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space. + +| Type | +| ------ | +| string | + +--- + +### `accessibilityRole` + +Tells the screen reader to treat the currently focused on element as having a specific role. + +On iOS, these roles map to corresponding Accessibility Traits. Image button has the same functionality as if the trait was set to both 'image' and 'button'. See the [Accessibility guide](accessibility.md#accessibilitytraits-ios) for more information. + +On Android, these roles have similar functionality on TalkBack as adding Accessibility Traits does on Voiceover in iOS + +| Type | +| ---------------------------------------------------- | +| [AccessibilityRole](accessibility#accessibilityrole) | + +--- + +### `accessibilityState` + +Tells the screen reader to treat the currently focused on element as being in a specific state. + +You can provide one state, no state, or multiple states. The states must be passed in through an object, e.g. `{selected: true, disabled: true}`. + +| Type | +| ------------------------------------------------------ | +| [AccessibilityState](accessibility#accessibilitystate) | + +--- + +### `accessibilityActions` + +Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The `accessibilityActions` property should contain a list of action objects. Each action object should contain the field name and label. + +See the [Accessibility guide](accessibility.md#accessibility-actions) for more information. + +| Type | Required | +| ----- | -------- | +| array | No | + +--- + +### `onAccessibilityAction` + +Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform. + +See the [Accessibility guide](accessibility.md#accessibility-actions) for more information. + +| Type | Required | +| -------- | -------- | +| function | No | + +--- + +### `accessible` + +When set to `true`, indicates that the view is an accessibility element. + +See the [Accessibility guide](accessibility#accessible-ios-android) for more information. + +| Type | Default | +| ------- | ------- | +| boolean | `true` | + +--- + +### `adjustsFontSizeToFit` + +Specifies whether fonts should be scaled down automatically to fit given style constraints. + +| Type | Default | +| ------- | ------- | +| boolean | `false` | + +--- + +### `allowFontScaling` + +Specifies whether fonts should scale to respect Text Size accessibility settings. + +On Android 14 and newer, scaling is [non-linear](https://developer.android.com/about/versions/14/features#non-linear-font-scaling): as the user's font scale setting grows, large fonts are scaled up less than small ones. + +| Type | Default | +| ------- | ------- | +| boolean | `true` | + +--- + +### `android_hyphenationFrequency`
Android
+ +Sets the frequency of automatic hyphenation to use when determining word breaks on Android API Level 23+. + +| Type | Default | +| ----------------------------------- | -------- | +| enum(`'none'`, `'normal'`,`'full'`) | `'none'` | + +--- + +### `aria-busy` + +Indicates an element is being modified and that assistive technologies may want to wait until the changes are complete before informing the user about the update. + +| Type | Default | +| ------- | ------- | +| boolean | false | + +--- + +### `aria-checked` + +Indicates the state of a checkable element. This field can either take a boolean or the "mixed" string to represent mixed checkboxes. + +| Type | Default | +| ---------------- | ------- | +| boolean, 'mixed' | false | + +--- + +### `aria-disabled` + +Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. + +| Type | Default | +| ------- | ------- | +| boolean | false | + +--- + +### `aria-expanded` + +Indicates whether an expandable element is currently expanded or collapsed. + +| Type | Default | +| ------- | ------- | +| boolean | false | + +--- + +### `aria-label` + +Defines a string value that labels an interactive element. + +| Type | +| ------ | +| string | + +--- + +### `aria-selected` + +Indicates whether a selectable element is currently selected or not. + +| Type | +| ------- | +| boolean | + +### `dataDetectorType`
Android
+ +Determines the types of data converted to clickable URLs in the text element. By default, no data types are detected. + +You can provide only one type. + +| Type | Default | +| ------------------------------------------------------------- | -------- | +| enum(`'phoneNumber'`, `'link'`, `'email'`, `'none'`, `'all'`) | `'none'` | + +--- + +### `disabled`
Android
+ +Specifies the disabled state of the text view for testing purposes. + +| Type | Default | +| ---- | ------- | +| bool | `false` | + +--- + +### `dynamicTypeRamp`
iOS
+ +The [Dynamic Type](https://developer.apple.com/documentation/uikit/uifont/scaling_fonts_automatically) ramp to apply to this element on iOS. + +| Type | Default | +| -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| enum(`'caption2'`, `'caption1'`, `'footnote'`, `'subheadline'`, `'callout'`, `'body'`, `'headline'`, `'title3'`, `'title2'`, `'title1'`, `'largeTitle'`) | `'body'` | + +--- + +### `ellipsizeMode` + +When `numberOfLines` is set, this prop defines how the text will be truncated. `numberOfLines` must be set in conjunction with this prop. + +This can be one of the following values: + +- `head` - The line is displayed so that the end fits in the container and the missing text at the beginning of the line is indicated by an ellipsis glyph. e.g., "...wxyz" +- `middle` - The line is displayed so that the beginning and end fit in the container and the missing text in the middle is indicated by an ellipsis glyph. "ab...yz" +- `tail` - The line is displayed so that the beginning fits in the container and the missing text at the end of the line is indicated by an ellipsis glyph. e.g., "abcd..." +- `clip` - Lines are not drawn past the edge of the text container. + +:::note +On Android, when `numberOfLines` is set to a value higher than `1`, only `tail` value will work correctly. +::: + +| Type | Default | +| ---------------------------------------------- | ------- | +| enum(`'head'`, `'middle'`, `'tail'`, `'clip'`) | `tail` | + +--- + +### `id` + +Used to locate this view from native code. Has precedence over `nativeID` prop. + +| Type | +| ------ | +| string | + +--- + +### `maxFontSizeMultiplier` + +Specifies the largest possible scale a font can reach when `allowFontScaling` is enabled. Possible values: + +- `null/undefined`: inherit from the parent node or the global default (0) +- `0`: no max, ignore parent/global default +- `>= 1`: sets the `maxFontSizeMultiplier` of this node to this value + +| Type | Default | +| ------ | ----------- | +| number | `undefined` | + +--- + +### `minimumFontScale` + +Specifies the smallest possible scale a font can reach when `adjustsFontSizeToFit` is enabled. (values 0.01-1.0). + +| Type | +| ------ | +| number | + +--- + +### `nativeID` + +Used to locate this view from native code. + +| Type | +| ------ | +| string | + +--- + +### `numberOfLines` + +Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number. Setting this property to `0` will result in unsetting this value, which means that no lines restriction will be applied. + +This prop is commonly used with `ellipsizeMode`. + +| Type | Default | +| ------ | ------- | +| number | `0` | + +--- + +### `onLayout` + +Invoked on mount and on layout changes. + +| Type | +| -------------------------------------------------------- | +| `md ({nativeEvent: [LayoutEvent](layoutevent)}) => void` | + +--- + +### `onLongPress` + +This function is called on long press. + +| Type | +| ------------------------------------------------------ | +| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | + +--- + +### `onMoveShouldSetResponder` + +Does this view want to "claim" touch responsiveness? This is called for every touch move on the `View` when it is not the responder. + +| Type | +| --------------------------------------------------------- | +| `md ({nativeEvent: [PressEvent](pressevent)}) => boolean` | + +--- + +### `onPress` + +Function called on user press, triggered after `onPressOut`. + +| Type | +| ------------------------------------------------------ | +| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | + +--- + +### `onPressIn` + +Called immediately when a touch is engaged, before `onPressOut` and `onPress`. + +| Type | +| ------------------------------------------------------ | +| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | + +--- + +### `onPressOut` + +Called when a touch is released. + +| Type | +| ------------------------------------------------------ | +| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | + +--- + +### `onResponderGrant` + +The View is now responding to touch events. This is the time to highlight and show the user what is happening. + +On Android, return true from this callback to prevent any other native components from becoming responder until this responder terminates. + +| Type | +| ----------------------------------------------------------------- | +| `md ({nativeEvent: [PressEvent](pressevent)}) => void ｜ boolean` | + +--- + +### `onResponderMove` + +The user is moving their finger. + +| Type | +| ------------------------------------------------------ | +| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | + +--- + +### `onResponderRelease` + +Fired at the end of the touch. + +| Type | +| ------------------------------------------------------ | +| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | + +--- + +### `onResponderTerminate` + +The responder has been taken from the `View`. Might be taken by other views after a call to `onResponderTerminationRequest`, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS) + +| Type | +| ------------------------------------------------------ | +| `md ({nativeEvent: [PressEvent](pressevent)}) => void` | + +--- + +### `onResponderTerminationRequest` + +Some other `View` wants to become a responder and is asking this `View` to release its responder. Returning `true` allows its release. + +| Type | +| --------------------------------------------------------- | +| `md ({nativeEvent: [PressEvent](pressevent)}) => boolean` | + +--- + +### `onStartShouldSetResponderCapture` + +If a parent `View` wants to prevent a child `View` from becoming a responder on a touch start, it should have this handler which returns `true`. + +| Type | +| --------------------------------------------------------- | +| `md ({nativeEvent: [PressEvent](pressevent)}) => boolean` | + +--- + +### `onTextLayout` + +Invoked on Text layout change. + +| Type | +| ---------------------------------------------------- | +| ([`TextLayoutEvent`](text#textlayoutevent)) => mixed | + +--- + +### `pressRetentionOffset` + +When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations. + +| Type | +| -------------------- | +| [Rect](rect), number | + +--- + +### `ref` + +A ref setter that will be assigned an [element node](element-nodes) when mounted. + +Note that `Text` components don't provide text nodes, the same way that paragraph elements (`

`) on Web are element nodes instead of text nodes. Text nodes can be found as their child nodes instead. + +--- + +### `role` + +`role` communicates the purpose of a component to the user of an assistive technology. Has precedence over the [`accessibilityRole`](text#accessibilityrole) prop. + +| Type | +| -------------------------- | +| [Role](accessibility#role) | + +--- + +### `selectable` + +Lets the user select text, to use the native copy and paste functionality. + +| Type | Default | +| ------- | ------- | +| boolean | `false` | + +--- + +### `selectionColor`

Android
+ +The highlight color of the text. + +| Type | +| --------------- | +| [color](colors) | + +--- + +### `style` + +| Type | +| -------------------------------------------------------------------- | +| [Text Style](text-style-props), [View Style Props](view-style-props) | + +--- + +### `suppressHighlighting`
iOS
+ +When `true`, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down. + +| Type | Default | +| ------- | ------- | +| boolean | `false` | + +--- + +### `testID` + +Used to locate this view in end-to-end tests. + +| Type | +| ------ | +| string | + +--- + +### `textBreakStrategy`
Android
+ +Set text break strategy on Android API Level 23+, possible values are `simple`, `highQuality`, `balanced`. + +| Type | Default | +| ----------------------------------------------- | ------------- | +| enum(`'simple'`, `'highQuality'`, `'balanced'`) | `highQuality` | + +--- + +### `lineBreakStrategyIOS`
iOS
+ +Set line break strategy on iOS 14+. Possible values are `none`, `standard`, `hangul-word` and `push-out`. + +| Type | Default | +| ----------------------------------------------------------- | -------- | +| enum(`'none'`, `'standard'`, `'hangul-word'`, `'push-out'`) | `'none'` | + +## Type Definitions + +### TextLayout + +`TextLayout` object is a part of [`TextLayoutEvent`](text#textlayoutevent) callback and contains the measurement data for `Text` line. + +#### Example + +```js +{ + capHeight: 10.496, + ascender: 14.624, + descender: 4, + width: 28.224, + height: 18.624, + xHeight: 6.048, + x: 0, + y: 0 +} +``` + +#### Properties + +| Name | Type | Optional | Description | +| --------- | ------ | -------- | ------------------------------------------------------------------- | +| ascender | number | No | The line ascender height after the text layout changes. | +| capHeight | number | No | Height of capital letter above the baseline. | +| descender | number | No | The line descender height after the text layout changes. | +| height | number | No | Height of the line after the text layout changes. | +| width | number | No | Width of the line after the text layout changes. | +| x | number | No | Line X coordinate inside the Text component. | +| xHeight | number | No | Distance between the baseline and median of the line (corpus size). | +| y | number | No | Line Y coordinate inside the Text component. | + +### TextLayoutEvent + +`TextLayoutEvent` object is returned in the callback as a result of a component layout change. It contains a key called `lines` with a value which is an array containing [`TextLayout`](text#textlayout) object corresponded to every rendered text line. + +#### Example + +```js +{ + lines: [ + TextLayout, + TextLayout, + // ... + ]; + target: 1127; +} +``` + +#### Properties + +| Name | Type | Optional | Description | +| ------ | --------------------------------------- | -------- | ----------------------------------------------------- | +| lines | array of [TextLayout](text#textlayout)s | No | Provides the TextLayout data for every rendered line. | +| target | number | No | The node id of the element. |