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:
import React, {useState} from 'react';
import {Text, StyleSheet} from 'react-native';
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 (
<Text style={styles.baseText}>
<Text style={styles.titleText} onPress={onPressTitle}>
{titleText}
{'\n'}
{'\n'}
</Text>
<Text numberOfLines={5}>{bodyText}</Text>
</Text>
);
};
const styles = StyleSheet.create({
container: {
flex: 1,
},
baseText: {
fontFamily: 'Cochin',
},
titleText: {
fontSize: 20,
fontWeight: 'bold',
},
});
export default TextInANest;
Nested text
Kepler allows you to display formatted text by annotating ranges of a string with specific formatting like bold or colored text. In practice, this is very tedious. For React Native, we decided to use tge web paradigm for this where you can nest text to achieve the same effect.
import React from 'react';
import {Text, StyleSheet} from 'react-native';
const BoldAndBeautiful = () => (
<Text style={styles.baseText}>
I am bold
<Text style={styles.innerText}> and red</Text>
</Text>
);
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
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:
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 <Text>
component. You cannot have a text node directly under a <View>
.
// BAD: will raise exception, can't have a text node as child of a <View>
<View>
Some text
</View>
// GOOD
<View>
<Text>
Some text
</Text>
</View>
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.
<View>
<MyAppText>
Text styled with the default font for the entire application
</MyAppText>
<MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>
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:
const MyAppHeaderText = ({children}) => {
return (
<MyAppText>
<Text style={{fontSize: 20}}>{children}</Text>
</MyAppText>
);
};
Composing MyAppText
in this way makes sure that we get the styles from a top-level component, but leaves us the ability to add or 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.
<Text style={{fontWeight: 'bold'}}>
I am bold
<Text style={{color: 'red'}}>and red</Text>
</Text>
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 |
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.
Type |
---|
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. For exmaple, {selected: true, disabled: true}
.
Type |
---|
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 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 for more information.
Type | Required |
---|---|
function | No |
accessible
When set to true
, indicates that the view is an accessibility element.
Type | Default |
---|---|
boolean | true |
adjustsFontSizeToFit
Specifies whether fonts should be scaled down automatically to fit given style constraints.
Type | Default |
---|---|
boolean | 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 |
ariaLabel
Deprecated. Use aria-label
instead.
The value for ariaLabel
refers to the name of the item, such as "Alexa, select Prime Video".
This prop is required you want your app to allow The user to perform voice selection based on the name. Providing the prop with a value does not result in the value being render as the title of the component, app needs to explicted render the same text value for the item.
Type |
---|
string |
aria-label
Defines a string value that labels an interactive element, that you can use to specify the name of the item in voice selection, such as "Alexa, select Prime Video".
This prop is required if the app wants to allow the user to perform voice selection based on the name.
Note that providing the prop with a value does not result in the value being render as the title of the component. The app needs to explictly render the same text value for the item.
Type |
---|
string |
aria-live
Indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.
- off Accessibility services should not announce changes to this view.
- polite Accessibility services should announce changes to this view.
- assertive Accessibility services should interrupt ongoing speech to immediately announce changes to this view.
Type | Default |
---|---|
enum('assertive' , 'off' , 'polite' ) |
'off' |
Type |
---|
string |
aria-selected
Indicates whether a selectable element is currently selected or not.
Type |
---|
boolean |
disabled
Specifies the disabled state of the text view for testing purposes.
Type | Default |
---|---|
boolean | false |
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.marquee
- If the text content exceeds the width of the text container, the text scrolls horizontally in a "marquee" effect to display the hidden content.- Requirements for this effect to take place:
- The
<Text>
component must be focusable. The marquee effect is applied whenever the focus enters or leaves the<Text>
component.
- The
- Requirements for this effect to take place:
When numberOfLines
is set to a value higher than 1
, only tail
value will work correctly.
Type | Default |
---|---|
enum('head' , 'middle' , 'tail' , 'clip' ,'marquee' ) |
tail |
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 |
selected
Specifies that the view is explicitly marked as chosen or active, regardless of user interaction or focus. When set to true
, it may trigger associated styling or behavioral changes.
For example, if ellipsizeMode
is set to marquee
, selected=true
starts the marquee animation.
Type | Default |
---|---|
boolean | false |
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 |
---|
({nativeEvent: [LayoutEvent](layoutevent)}) => void |
onPress
Function called on user press, triggered after onPressOut
.
Type |
---|
({nativeEvent: [PressEvent](pressevent)}) => void |
onTextLayout
Invoked on Text layout change.
Type |
---|
(TextLayoutEvent ) => mixed |
role
role
communicates the purpose of a component to the user of an assistive technology. Has precedence over the accessibilityRole
prop.
Type |
---|
Role |
style
Type |
---|
Text Style, View Style Props |
testID
Used to locate this view in end-to-end tests.
Type |
---|
string |
alexaEntityType - Kepler Only
Represents the value for the type of object to pass to the Alexa UIController Interface. This is an optional prop and specific to Alexa UIController Interface support, it maps to the entity.type
field from the Alexa UIController Interface. For additiona information, see Alexa UIController API doc.
Type |
---|
enum('Thing', 'VideoObject', 'ItemList', 'SoftwareApplication') |
alexaExternalIds - Kepler Only
This is an optional prop and specific to Alexa UIController Interface support, it maps to the entity.ExternalIds
field from the Alexa UIController Interface. For additiona information, see Alexa UIController API doc.
The entity.ExternalIds
are the identifiers for this entity unique within the scope of this endpoint. The entity.externalIds
field is opaque to Alexa and is only used to include in directives from Alexa. The identifiers reported in entity.externalIds
are required to be understood by the endpoint on all directive commands that accept an entity structure.
Type |
---|
object: {key: "string", value: "string"} |
keplerAtlLabels - Kepler Only
The value for keplerAltLabels
refers to the list of alternate names for the item.
Note: This property replaces keplerAtlLabels
. keplerAtlLabels
is deprecated and will be removed in a future release.
This prop is required if the app wants to allow user to perform voice selection on the same item with different names.
Type |
---|
Array of string |
Type Definitions
TextLayout
TextLayout
object is a part of TextLayoutEvent
callback and contains the measurement data for Text
line.
Example
{
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
object corresponded to every rendered text line.
Example
{
lines: [
TextLayout,
TextLayout,
// ...
];
target: 1127;
}
Properties
Name | Type | Optional | Description |
---|---|---|---|
lines | array of TextLayout | No | Provides the TextLayout data for every rendered line. |
target | number | No | The node id of the element. |
---
id
Used to locate this view from native code. Has precedence over nativeID
prop.
Type |
---|
string |
keplerAltLabels - Kepler Only
The value for keplerAltLabels
refers to the list of alternate names for the item.
Note: This property replaces keplerAtlLabels
. keplerAtlLabels
is deprecated and will be removed in a future release.
This prop is required if the app wants to allow user to perform voice selection on the same item with different names.
Type |
---|
Array of string |
Last updated: Sep 30, 2025