Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 71 ยท Components and Interaction

TextInput in Depth: Props, Events and Real-Time Input

A complete tour of React Native TextInput: autofill and keyboard props, selection, caret and return key options, the event order, and real-time input handling with masks.

Text and TextInput showed the basics: a controlled input, the right keyboard and moving between fields. TextInput has many more props, and most of them exist to fix one specific annoyance: a keyboard that capitalizes an email address, a password manager that does not fill the field, a return key that says the wrong thing. This lesson organizes them by the problem they solve, then covers the events and real-time input handling.

What runs on this site. TextInput talks to the native keyboard, so the real React Native code is read-only. The runnable examples are stand-ins: an HTML input that fires the same events in the same order, and plain functions for masks and validation that are identical to what you would use on a device.

Props that decide the keyboard

Prop What it does
keyboardType "default", "email-address", "numeric", "number-pad", "decimal-pad", "phone-pad", "url"
inputMode the web-style equivalent, such as "email", "numeric", "decimal", "tel", "url", "search"
returnKeyType the label or icon on the return key: "done", "next", "go", "search", "send"
returnKeyLabel (Android) a custom text for the return key
enterKeyHint the web-style way to say the same thing as returnKeyType
keyboardAppearance (iOS) "default", "light" or "dark" keyboard
enablesReturnKeyAutomatically (iOS) disables the return key until something is typed
showSoftInputOnFocus (Android) set to false to focus the field without opening the keyboard, for custom keypads

Pick keyboardType for the data and returnKeyType for the action. A numeric field needs keyboardType="number-pad" or "decimal-pad", but both still allow pasted letters, so validate the text too.

Props that decide how text is treated

  • autoCapitalize: "none", "sentences" (the default), "words" or "characters". Use "none" for emails, usernames and codes.
  • autoCorrect and spellCheck: set both to false for emails, IDs and code. Autocorrect changing ncount into account in a username box is a classic bug report.
  • secureTextEntry: hides characters for passwords. It also turns off keyboard suggestions and caching.
  • maxLength: a hard limit on the number of characters.
  • multiline and numberOfLines: a text area. In a multiline input textAlignVertical="top" (Android) puts the text at the top, because it is centred by default.
  • editable={false}: a read-only field that still looks like an input.
  • defaultValue versus value: defaultValue sets the first text of an uncontrolled input; value makes it controlled. Pick one, never both.

Autofill and password managers

Password managers and the OS can fill fields, but only when they can recognise them.

Prop Platform Example
autoComplete Android (and the type on other platforms) "email", "username", "password", "new-password", "one-time-code", "tel", "name", "off"
textContentType iOS "emailAddress", "username", "password", "newPassword", "oneTimeCode"
importantForAutofill Android "yes", "no", "auto"
passwordRules iOS the rules for generated passwords, for example "minlength: 12; required: lower; required: upper"

The older autoCompleteType prop was renamed autoComplete; if you see the old name in a tutorial, change it. Set both autoComplete and textContentType so iOS and Android behave the same. For a one-time code from an SMS, textContentType="oneTimeCode" and autoComplete="one-time-code" let the keyboard suggest the code it just received.

JSX
<TextInput
  value={email}
  onChangeText={setEmail}
  keyboardType="email-address"
  autoCapitalize="none"
  autoCorrect={false}
  autoComplete="email"
  textContentType="emailAddress"
  returnKeyType="next"
  placeholder="[email protected]"
/>

Selection, caret and focus behaviour

  • selectTextOnFocus: selects all text when the field is focused. Good for editing a quantity.
  • clearTextOnFocus (iOS): clears the field on focus, which is rarely what users expect.
  • clearButtonMode (iOS single line): shows an "x" button "never", "while-editing", "unless-editing" or "always".
  • caretHidden, contextMenuHidden, selectionColor: hide the caret, hide the copy and paste menu, and colour the caret and selection handles.
  • selection: controls the selection range, as { start, end }. Use it with onSelectionChange, for instance to put the caret at the end after formatting.
  • autoFocus: focuses when the screen mounts. It can fight with screen transitions, so prefer calling ref.current.focus() when the screen has appeared.
  • Instance methods: focus(), blur(), clear() and isFocused().
  • dataDetectorTypes (iOS, non-editable multiline only): turn phone numbers or links in text into tappable links.
  • Android visuals: underlineColorAndroid (use "transparent" to hide the line), inlineImageLeft and inlineImagePadding for a small icon inside the field.

Events and their order

TextInput has more events than onChangeText:

Event Argument Fires
onFocus event the field gains focus
onKeyPress nativeEvent.key a key was pressed, before the text changes
onChangeText the new string after every change (the one you use most)
onChange nativeEvent.text after every change, with the full event
onSelectionChange nativeEvent.selection the caret or selection moved
onContentSizeChange nativeEvent.contentSize the text size changed (multiline growth)
onSubmitEditing event the user pressed the return key
onEndEditing event editing ended, because of submit or blur
onBlur event the field lost focus
onLayout nativeEvent.layout after the layout, with x, y, width, height

On a multiline input pressing return inserts a line; use submitBehavior ("submit", "blurAndSubmit" or "newline") to change that. It replaces the older blurOnSubmit.

onKeyPress sees keys such as Backspace ("Backspace") and Enter, which onChangeText cannot tell you about.

Event order for typing, selecting and submitting (stand-in)

Typing one letter gives onKeyPress first and onChangeText after it, because the key press happens before the text exists. Pressing Enter gives onSubmitEditing, and moving away gives onEndEditing followed by onBlur.

Real-time input handling

"Real-time" means reacting to every change: formatting while typing, limiting characters, live validation. The rules are the same as for any controlled input: take the incoming text, transform it with a pure function, store the result.

JSX
function PhoneField() {
  const [phone, setPhone] = useState('');
  return (
    <TextInput
      value={phone}
      onChangeText={(t) => setPhone(formatPhone(t))}
      keyboardType="phone-pad"
      maxLength={14}
    />
  );
}

A mask function should (1) strip everything that is not allowed, (2) cut to the limit, (3) re-insert the separators. Because it is pure, you can test it without a device.

Masks and filters for live typing

A few practical points. A mask that rewrites the text can make the caret jump to the end on some platforms when the user edits in the middle; keep masks simple, or manage selection yourself. Do not format a field that the user may paste into without handling pasted text. Validate on blur (onEndEditing or onBlur) for error messages, not on every key, so people are not scolded mid-word (see Forms and Validation). And debounce anything slow, such as a search request, instead of calling it on each onChangeText.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which event fires first when the user types a letter?

    onKeyPress reports the key before the text changes. onChangeText then reports the new string.
  2. 2. Which props make a password manager fill an email field on both platforms?

    autoComplete serves Android and textContentType serves iOS. Setting both gives consistent autofill.
  3. 3. You want a field to focus without opening the keyboard because you show a custom keypad. Which prop (Android) does that?

    showSoftInputOnFocus={false} keeps the focus and the caret but does not show the software keyboard.
  4. 4. What is a safe way to implement a live phone mask?

    The controlled-input rule applies: compute the new value from the incoming text and store it. A pure function is easy to test.

Summary

  • Choose keyboardType for the data and returnKeyType for the action; validate pasted text anyway.
  • Turn off autoCapitalize, autoCorrect and spellCheck for emails, usernames and codes.
  • Set autoComplete (Android) and textContentType (iOS) so autofill and password managers work.
  • Selection, caret and focus props (selectTextOnFocus, selection, clearButtonMode, showSoftInputOnFocus) fix specific UI problems; many are platform-specific.
  • Events run in order: focus, key press, change text, selection change, submit, end editing, blur.
  • For real-time handling, filter and format with a pure function and store the result; validate on blur.

Next: Modals, Alerts and Sheets.