TextInput

A foundational component for inputting text into the app via a keyboard. Props provide configurability for several features, such as auto-correction, auto-capitalization, placeholder text, and different keyboard types, such as a numeric keypad.

Import

import { TextInput } from 'react-native';

Basic Usage

import React, { useState } from 'react';
import { TextInput, StyleSheet } from 'react-native';

function BasicTextInput() {
  const [text, setText] = useState('');

  return (
    <TextInput
      style={styles.input}
      value={text}
      onChangeText={setText}
      placeholder="Enter text here"
    />
  );
}

const styles = StyleSheet.create({
  input: {
    height: 40,
    borderColor: 'gray',
    borderWidth: 1,
    paddingHorizontal: 10,
  },
});

Props

Value Props

string

The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided.

string

Provides an initial value that will change when the user starts typing. Useful for use-cases where you do not want to deal with listening to events and updating the value prop to keep the controlled state in sync.

Input Behavior

boolean

default:"true"

If false, text is not editable.

boolean

default:"false"

If true, the text input can be multiple lines. The default value is false.

number

Limits the maximum number of characters that can be entered.

number

Sets the number of lines for a TextInput. Use it with multiline set to true to be able to fill the lines.

Keyboard Configuration

KeyboardType

default:"'default'"

Determines which keyboard to open.Cross-platform values: ‘default’, ‘number-pad’, ‘decimal-pad’, ‘numeric’, ‘email-address’, ‘phone-pad’, ‘url’iOS-only: ‘ascii-capable’, ‘numbers-and-punctuation’, ‘name-phone-pad’, ‘twitter’, ‘web-search’Android-only: ‘visible-password’

ReturnKeyType

Determines how the return key should look.Cross-platform: ‘done’, ‘go’, ‘next’, ‘search’, ‘send’iOS: ‘default’, ‘google’, ‘join’, ‘route’, ‘yahoo’, ‘emergency-call’Android: ‘none’, ‘previous’

'none' | 'sentences' | 'words' | 'characters'

default:"'sentences'"

Can tell TextInput to automatically capitalize certain characters.

characters - All characters
words - First letter of each word
sentences - First letter of each sentence (default)
none - Don’t auto capitalize anything

boolean

If false, disables auto-correct. The default value is true.

string

Specifies autocomplete hints for the system, so it can provide autofill. On Android, the system will always attempt to offer autofill by using heuristics to identify the type of content. On iOS, you must explicitly set the autocomplete type.

InputMode

Works like the inputmode attribute in HTML, it determines which keyboard to open, e.g. numeric and has precedence over keyboardType.Options: ‘none’, ‘text’, ‘decimal’, ‘numeric’, ‘tel’, ‘search’, ‘email’, ‘url’

EnterKeyHint

Determines what text should be shown to the return key on virtual keyboards.Options: ‘enter’, ‘done’, ‘go’, ‘next’, ‘previous’, ‘search’, ‘send’

Visual Props

string

The string that will be rendered before text input has been entered.

color

The text color of the placeholder string.

TextStyle

Styles to apply to the text input.

boolean

default:"false"

If true, the text input obscures the text entered so that sensitive text like passwords stay secure.

Selection Props

{start: number, end?: number}

The start and end of the text input’s selection. Set start and end to the same value to position the cursor.

color

The highlight and cursor color of the text input.

color

When provided it will set the color of the cursor (or “caret”) in the component. Unlike the behavior of selectionColor the cursor color will be set independently from the color of the text selection box.

boolean

default:"false"

If true, all text will automatically be selected on focus.

Event Handlers

(text: string) => void

Callback that is called when the text input’s text changes. Changed text is passed as a single string argument to the callback handler.

(event: ChangeEvent) => void

Callback that is called when the text input’s text changes.

(event: FocusEvent) => void

Callback that is called when the text input is focused.

(event: BlurEvent) => void

Callback that is called when the text input is blurred.

(event: SubmitEditingEvent) => void

Callback that is called when the text input’s submit button is pressed.

(event: EndEditingEvent) => void

Callback that is called when text input ends.

(event: KeyPressEvent) => void

Callback that is called when a key is pressed. This will be called with {nativeEvent: {key: keyValue}} where keyValue is ‘Enter’ or ‘Backspace’ for respective keys and the typed-in character otherwise including ’ ’ for space.

(event: SelectionChangeEvent) => void

Callback that is called when the text input selection is changed.

(event: ContentSizeChangeEvent) => void

Callback that is called when the text input’s content size changes. This will be called with {nativeEvent: {contentSize: {width, height}}}.

Identification Props

string

Used to reference the text input from native code.

string

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

Platform-Specific Props

iOS
Android

'never' | 'while-editing' | 'unless-editing' | 'always'

default:"'never'"

When the clear button should appear on the right side of the text view.

boolean

default:"false"

If true, clears the text field automatically when editing begins.

boolean

default:"false"

If true, the keyboard disables the return key when there is no text and automatically enables it when there is text.

'default' | 'light' | 'dark'

Determines the color of the keyboard.

boolean

If false, disables spell-check style (i.e. red underlines). The default value is inherited from autoCorrect.

TextContentType

Give the keyboard and the system information about the expected semantic meaning for the content that users enter.Options include: ‘none’, ‘URL’, ‘addressCity’, ‘addressCityAndState’, ‘addressState’, ‘countryName’, ‘creditCardNumber’, ‘emailAddress’, ‘familyName’, ‘fullStreetAddress’, ‘givenName’, ‘jobTitle’, ‘location’, ‘middleName’, ‘name’, ‘namePrefix’, ‘nameSuffix’, ‘nickname’, ‘organizationName’, ‘postalCode’, ‘streetAddressLine1’, ‘streetAddressLine2’, ‘sublocality’, ‘telephoneNumber’, ‘username’, ‘password’, ‘newPassword’, ‘oneTimeCode’

string

When using textContentType as newPassword, we can let the OS know the requirements of the password so that it can autogenerate one that will satisfy them.

Methods

method

Makes the text input get focus.

textInputRef.focus();

method

Makes the text input lose focus.

textInputRef.blur();

method

Removes all text from the TextInput.

textInputRef.clear();

method

Returns true if the input is currently focused; false otherwise.

const focused = textInputRef.isFocused();

Examples

Controlled Input

import { TextInput, Text, View, StyleSheet } from 'react-native';
import { useState } from 'react';

function ControlledInput() {
  const [text, setText] = useState('');

  return (
    <View style={styles.container}>
      <TextInput
        style={styles.input}
        value={text}
        onChangeText={setText}
        placeholder="Type here..."
      />
      <Text>You typed: {text}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 20,
  },
  input: {
    height: 40,
    borderWidth: 1,
    borderColor: '#ccc',
    paddingHorizontal: 10,
    marginBottom: 10,
  },
});

Multiline Input

import { TextInput, StyleSheet } from 'react-native';
import { useState } from 'react';

function MultilineInput() {
  const [text, setText] = useState('');

  return (
    <TextInput
      style={styles.input}
      multiline
      numberOfLines={4}
      value={text}
      onChangeText={setText}
      placeholder="Enter multiple lines..."
    />
  );
}

const styles = StyleSheet.create({
  input: {
    height: 100,
    borderWidth: 1,
    borderColor: '#ccc',
    padding: 10,
    textAlignVertical: 'top',
  },
});

Password Input

import { TextInput, StyleSheet } from 'react-native';
import { useState } from 'react';

function PasswordInput() {
  const [password, setPassword] = useState('');

  return (
    <TextInput
      style={styles.input}
      value={password}
      onChangeText={setPassword}
      placeholder="Enter password"
      secureTextEntry
      autoCapitalize="none"
      autoCorrect={false}
    />
  );
}

const styles = StyleSheet.create({
  input: {
    height: 40,
    borderWidth: 1,
    borderColor: '#ccc',
    paddingHorizontal: 10,
  },
});

Input with Ref

import { TextInput, Button, View, StyleSheet } from 'react-native';
import { useRef } from 'react';

function InputWithRef() {
  const inputRef = useRef(null);

  return (
    <View style={styles.container}>
      <TextInput
        ref={inputRef}
        style={styles.input}
        placeholder="Click button to focus"
      />
      <Button title="Focus Input" onPress={() => inputRef.current?.focus()} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 20,
  },
  input: {
    height: 40,
    borderWidth: 1,
    borderColor: '#ccc',
    paddingHorizontal: 10,
    marginBottom: 10,
  },
});

Core Components

User Interface

List Components

Android Components

iOS Components

Import

Basic Usage

Props

Value Props

Input Behavior

Keyboard Configuration

Visual Props

Selection Props

Event Handlers

Identification Props

Platform-Specific Props

Methods

Examples

Controlled Input

Multiline Input

Password Input

Input with Ref

​Import

​Basic Usage

​Props

​Value Props

​Input Behavior

​Keyboard Configuration

​Visual Props

​Selection Props

​Event Handlers

​Identification Props

​Platform-Specific Props

​Methods

​Examples

​Controlled Input

​Multiline Input

​Password Input

​Input with Ref

Import

Basic Usage

Props

Value Props

Input Behavior

Keyboard Configuration

Visual Props

Selection Props

Event Handlers

Identification Props

Platform-Specific Props

Methods

Examples

Controlled Input

Multiline Input

Password Input

Input with Ref