react-native-macos/docs/text.md

---
id: text
title: Text
layout: docs
category: components
permalink: docs/text.html
next: textinput
previous: tabbarios-item
---

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:

```ReactNativeWebPlayer
import React, { Component } from 'react';
import { AppRegistry, Text, StyleSheet } from 'react-native';

export default class TextInANest extends Component {
  constructor(props) {
    super(props);
    this.state = {
      titleText: "Bird's Nest",
      bodyText: 'This is not really a bird nest.'
    };
  }

  render() {
    return (
      <Text style={styles.baseText}>
        <Text style={styles.titleText} onPress={this.onPressTitle}>
          {this.state.titleText}{'\n'}{'\n'}
        </Text>
        <Text numberOfLines={5}>
          {this.state.bodyText}
        </Text>
      </Text>
    );
  }
}

const styles = StyleSheet.create({
  baseText: {
    fontFamily: 'Cochin',
  },
  titleText: {
    fontSize: 20,
    fontWeight: 'bold',
  },
});

// skip this line if using Create React Native App
AppRegistry.registerComponent('TextInANest', () => TextInANest);
```

## Nested text

Both iOS and Android 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 web paradigm for
this where you can nest text to achieve the same effect.


```ReactNativeWebPlayer
import React, { Component } from 'react';
import { AppRegistry, Text } from 'react-native';

export default class BoldAndBeautiful extends Component {
  render() {
    return (
      <Text style={{fontWeight: 'bold'}}>
        I am bold
        <Text style={{color: 'red'}}>
          and red
        </Text>
      </Text>
    );
  }
}

// skip this line if using Create React Native App
AppRegistry.registerComponent('AwesomeProject', () => BoldAndBeautiful);
```

Behind the scenes, React Native converts this to a flat `NSAttributedString`
or `SpannableString` that contains the following information:

```javascript
"I am bold and red"
0-9: bold
9-17: bold, red
```

## Nested views (iOS only)

On iOS, you can nest views within your Text component. Here's an example:

```ReactNativeWebPlayer
import React, { Component } from 'react';
import { AppRegistry, Text, View } from 'react-native';

export default class BlueIsCool extends Component {
  render() {
    return (
      <Text>
        There is a blue square
        <View style={{width: 50, height: 50, backgroundColor: 'steelblue'}} />
        in between my text.
      </Text>
    );
  }
}

// skip this line if using Create React Native App
AppRegistry.registerComponent('AwesomeProject', () => BlueIsCool);
```

> In order to use this feature, you must give the view a `width` and a `height`.

## Containers

The `<Text>` element is special relative to layout: everything inside is no
longer using the flexbox layout but using text layout. This means that
elements inside of a `<Text>` are no longer rectangles, but wrap when they
see the end of the line.

```javascript
<Text>
  <Text>First part and </Text>
  <Text>second part</Text>
</Text>
// Text container: all the text flows as if it was one
// |First part |
// |and second |
// |part       |

<View>
  <Text>First part and </Text>
  <Text>second part</Text>
</View>
// View container: each text is 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 `<Text>` component**. You cannot have a text node directly
under a `<View>`.


```javascript
// 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.
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.

```javascript
<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 simply renders out its
children into a `Text` component with styling, then `MyAppHeaderText` can be
defined as follows:

```javascript
class MyAppHeaderText extends Component {
  render() {
    <MyAppText>
      <Text style={{fontSize: 20}}>
        {this.props.children}
      </Text>
    </MyAppText>
  }
}
```

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.

```javascript
<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.

### Props

- [`selectable`](docs/text.html#selectable)
- [`accessible`](docs/text.html#accessible)
- [`ellipsizeMode`](docs/text.html#ellipsizemode)
- [`nativeID`](docs/text.html#nativeid)
- [`numberOfLines`](docs/text.html#numberoflines)
- [`onLayout`](docs/text.html#onlayout)
- [`onLongPress`](docs/text.html#onlongpress)
- [`onPress`](docs/text.html#onpress)
- [`pressRetentionOffset`](docs/text.html#pressretentionoffset)
- [`allowFontScaling`](docs/text.html#allowfontscaling)
- [`style`](docs/text.html#style)
- [`testID`](docs/text.html#testid)
- [`disabled`](docs/text.html#disabled)
- [`selectionColor`](docs/text.html#selectioncolor)
- [`textBreakStrategy`](docs/text.html#textbreakstrategy)
- [`adjustsFontSizeToFit`](docs/text.html#adjustsfontsizetofit)
- [`minimumFontScale`](docs/text.html#minimumfontscale)
- [`suppressHighlighting`](docs/text.html#suppresshighlighting)






---

# Reference

## Props

### `selectable`

Lets the user select text, to use the native copy and paste functionality.

| Type | Required |
| - | - |
| bool | No |




---

### `accessible`

When set to `true`, indicates that the view is an accessibility element. The default value
for a `Text` element is `true`.

See the
[Accessibility guide](docs/accessibility.html#accessible-ios-android)
for more information.

| Type | Required |
| - | - |
| bool | No |




---

### `ellipsizeMode`

When `numberOfLines` is set, this prop defines how 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.

The default is `tail`.

> `clip` is working only for iOS

| Type | Required |
| - | - |
| enum('head', 'middle', 'tail', 'clip') | No |




---

### `nativeID`

Used to locate this view from native code.

| Type | Required |
| - | - |
| string | No |




---

### `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.

This prop is commonly used with `ellipsizeMode`.

| Type | Required |
| - | - |
| number | No |




---

### `onLayout`

Invoked on mount and layout changes with

  `{nativeEvent: {layout: {x, y, width, height}}}`

| Type | Required |
| - | - |
| function | No |




---

### `onLongPress`

This function is called on long press.

e.g., `onLongPress={this.increaseSize}>`

| Type | Required |
| - | - |
| function | No |




---

### `onPress`

This function is called on press.

e.g., `onPress={() => console.log('1st')}`

| Type | Required |
| - | - |
| function | No |




---

### `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 | Required |
| - | - |
| object: {top: number, left: number, bottom: number, right: number} | No |




---

### `allowFontScaling`

Specifies whether fonts should scale to respect Text Size accessibility settings. The
default is `true`.

| Type | Required |
| - | - |
| bool | No |




---

### `style`



| Type | Required |
| - | - |
| style | No |


  - [View Style Props...](docs/view-style-props.html#style)

  - **`textShadowOffset`**: object: {width: number,height: number}

  - **`color`**: [color](docs/colors.html)

  - **`fontSize`**: number

  - **`fontStyle`**: enum('normal', 'italic')

  - **`fontWeight`**: enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')

    Specifies font weight. The values 'normal' and 'bold' are supported for
    most fonts. Not all fonts have a variant for each of the numeric values,
    in that case the closest one is chosen.

  - **`lineHeight`**: number

  - **`textAlign`**: enum('auto', 'left', 'right', 'center', 'justify')

    Specifies text alignment. The value 'justify' is only supported on iOS and
    fallbacks to `left` on Android.

  - **`textDecorationLine`**: enum('none', 'underline', 'line-through', 'underline line-through')

  - **`textShadowColor`**: [color](docs/colors.html)

  - **`fontFamily`**: string

  - **`textShadowRadius`**: number

  - **`includeFontPadding`**: bool (_Android_)

    Set to `false` to remove extra font padding intended to make space for certain ascenders / descenders.
    With some fonts, this padding can make text look slightly misaligned when centered vertically.
    For best results also set `textAlignVertical` to `center`. Default is true.
    

  - **`textAlignVertical`**: enum('auto', 'top', 'bottom', 'center') (_Android_)

  - **`fontVariant`**: array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums') (_iOS_)

  - **`letterSpacing`**: number (_iOS_)

  - **`textDecorationColor`**: [color](docs/colors.html) (_iOS_)

  - **`textDecorationStyle`**: enum('solid', 'double', 'dotted', 'dashed') (_iOS_)

  - **`writingDirection`**: enum('auto', 'ltr', 'rtl') (_iOS_)



---

### `testID`

Used to locate this view in end-to-end tests.

| Type | Required |
| - | - |
| string | No |




---

### `disabled`

Specifies the disabled state of the text view for testing purposes


| Type | Required | Platform |
| - | - | - |
| bool | No | Android  |




---

### `selectionColor`

The highlight color of the text.


| Type | Required | Platform |
| - | - | - |
| [color](docs/colors.html) | No | Android  |




---

### `textBreakStrategy`

Set text break strategy on Android API Level 23+, possible values are `simple`, `highQuality`, `balanced`
The default value is `highQuality`.


| Type | Required | Platform |
| - | - | - |
| enum('simple', 'highQuality', 'balanced') | No | Android  |




---

### `adjustsFontSizeToFit`

Specifies whether font should be scaled down automatically to fit given style constraints.


| Type | Required | Platform |
| - | - | - |
| bool | No | iOS  |




---

### `minimumFontScale`

Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).


| Type | Required | Platform |
| - | - | - |
| number | No | iOS  |




---

### `suppressHighlighting`

When `true`, no visual change is made when text is pressed down. By
default, a gray oval highlights the text on press down.


| Type | Required | Platform |
| - | - | - |
| bool | No | iOS  |