react-native/website/versioned_docs/0.21/textinput.md

---
id: version-0.21-textinput
title: textinput
original_id: textinput
---
<a id="content"></a><table width="100%"><tbody><tr><td><h1><a class="anchor" name="textinput"></a>TextInput <a class="hash-link" href="undefined#textinput">#</a></h1></td><td style="text-align:right;"><a target="_blank" href="https://github.com/facebook/react-native/blob/master/Libraries/Components/TextInput/TextInput.js">Edit on GitHub</a></td></tr></tbody></table><div><div><p>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.</p><p>The simplest use case is to plop down a <code>TextInput</code> and subscribe to the
<code>onChangeText</code> events to read the user input. There are also other events,
such as <code>onSubmitEditing</code> and <code>onFocus</code> that can be subscribed to. A simple
example:</p><div class="prism language-javascript">  &lt;TextInput
    style<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span>height<span class="token punctuation">:</span> <span class="token number">40</span><span class="token punctuation">,</span> borderColor<span class="token punctuation">:</span> <span class="token string">'gray'</span><span class="token punctuation">,</span> borderWidth<span class="token punctuation">:</span> <span class="token number">1</span><span class="token punctuation">}</span><span class="token punctuation">}</span>
    onChangeText<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">(</span>text<span class="token punctuation">)</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">setState<span class="token punctuation">(</span></span><span class="token punctuation">{</span>text<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">}</span>
    value<span class="token operator">=</span><span class="token punctuation">{</span><span class="token keyword">this</span><span class="token punctuation">.</span>state<span class="token punctuation">.</span>text<span class="token punctuation">}</span>
  <span class="token operator">/</span><span class="token operator">&gt;</span></div><p>Note that some props are only available with <code>multiline={true/false}</code>:</p></div><h3><a class="anchor" name="props"></a>Props <a class="hash-link" href="undefined#props">#</a></h3><div class="props"><div class="prop"><h4 class="propTitle"><a class="anchor" name="view"></a><a href="view.html#props">View props...</a> <a class="hash-link" href="undefined#view">#</a></h4></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="autocapitalize"></a>autoCapitalize <span class="propType">enum('none', 'sentences', 'words', 'characters')</span> <a class="hash-link" href="undefined#autocapitalize">#</a></h4><div><p>Can tell TextInput to automatically capitalize certain characters.</p><ul><li>characters: all characters,</li><li>words: first letter of each word</li><li>sentences: first letter of each sentence (default)</li><li>none: don't auto capitalize anything</li></ul></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="autocorrect"></a>autoCorrect <span class="propType">bool</span> <a class="hash-link" href="undefined#autocorrect">#</a></h4><div><p>If false, disables auto-correct. The default value is true.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="autofocus"></a>autoFocus <span class="propType">bool</span> <a class="hash-link" href="undefined#autofocus">#</a></h4><div><p>If true, focuses the input on componentDidMount.
The default value is false.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="defaultvalue"></a>defaultValue <span class="propType">string</span> <a class="hash-link" href="undefined#defaultvalue">#</a></h4><div><p>Provides an initial value that will change when the user starts typing.
Useful for simple use-cases where you don't want to deal with listening
to events and updating the value prop to keep the controlled state in sync.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="editable"></a>editable <span class="propType">bool</span> <a class="hash-link" href="undefined#editable">#</a></h4><div><p>If false, text is not editable. The default value is true.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="keyboardtype"></a>keyboardType <span class="propType">enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search')</span> <a class="hash-link" href="undefined#keyboardtype">#</a></h4><div><p>Determines which keyboard to open, e.g.<code>numeric</code>.</p><p>The following values work across platforms:
- default
- numeric
- email-address</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="maxlength"></a>maxLength <span class="propType">number</span> <a class="hash-link" href="undefined#maxlength">#</a></h4><div><p>Limits the maximum number of characters that can be entered. Use this
instead of implementing the logic in JS to avoid flicker.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="multiline"></a>multiline <span class="propType">bool</span> <a class="hash-link" href="undefined#multiline">#</a></h4><div><p>If true, the text input can be multiple lines.
The default value is false.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onblur"></a>onBlur <span class="propType">function</span> <a class="hash-link" href="undefined#onblur">#</a></h4><div><p>Callback that is called when the text input is blurred</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onchange"></a>onChange <span class="propType">function</span> <a class="hash-link" href="undefined#onchange">#</a></h4><div><p>Callback that is called when the text input's text changes.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onchangetext"></a>onChangeText <span class="propType">function</span> <a class="hash-link" href="undefined#onchangetext">#</a></h4><div><p>Callback that is called when the text input's text changes.
Changed text is passed as an argument to the callback handler.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onendediting"></a>onEndEditing <span class="propType">function</span> <a class="hash-link" href="undefined#onendediting">#</a></h4><div><p>Callback that is called when text input ends.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onfocus"></a>onFocus <span class="propType">function</span> <a class="hash-link" href="undefined#onfocus">#</a></h4><div><p>Callback that is called when the text input is focused</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onlayout"></a>onLayout <span class="propType">function</span> <a class="hash-link" href="undefined#onlayout">#</a></h4><div><p>Invoked on mount and layout changes with <code>{x, y, width, height}</code>.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onselectionchange"></a>onSelectionChange <span class="propType">function</span> <a class="hash-link" href="undefined#onselectionchange">#</a></h4><div><p>Callback that is called when the text input selection is changed</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onsubmitediting"></a>onSubmitEditing <span class="propType">function</span> <a class="hash-link" href="undefined#onsubmitediting">#</a></h4><div><p>Callback that is called when the text input's submit button is pressed.
Invalid if multiline={true} is specified.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="placeholder"></a>placeholder <span class="propType">string</span> <a class="hash-link" href="undefined#placeholder">#</a></h4><div><p>The string that will be rendered before text input has been entered</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="placeholdertextcolor"></a>placeholderTextColor <span class="propType">string</span> <a class="hash-link" href="undefined#placeholdertextcolor">#</a></h4><div><p>The text color of the placeholder string</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="securetextentry"></a>secureTextEntry <span class="propType">bool</span> <a class="hash-link" href="undefined#securetextentry">#</a></h4><div><p>If true, the text input obscures the text entered so that sensitive text
like passwords stay secure. The default value is false.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="selectioncolor"></a>selectionColor <span class="propType">string</span> <a class="hash-link" href="undefined#selectioncolor">#</a></h4><div><p>The highlight (and cursor on ios) color of the text input</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="style"></a>style <span class="propType"><a href="text.html#style">Text#style</a></span> <a class="hash-link" href="undefined#style">#</a></h4><div><p>Styles</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="value"></a>value <span class="propType">string</span> <a class="hash-link" href="undefined#value">#</a></h4><div><p>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. For most uses this works great, but in some
cases this may cause flickering - one common cause is preventing edits
by keeping value the same. In addition to simply setting the same value,
either set <code>editable={false}</code>, or set/update <code>maxLength</code> to prevent
unwanted edits without flicker.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="numberoflines"></a><span class="platform">android</span>numberOfLines <span class="propType">number</span> <a class="hash-link" href="undefined#numberoflines">#</a></h4><div><p>Sets the number of lines for a TextInput. Use it with multiline set to
true to be able to fill the lines.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="underlinecolorandroid"></a><span class="platform">android</span>underlineColorAndroid <span class="propType">string</span> <a class="hash-link" href="undefined#underlinecolorandroid">#</a></h4><div><p>The color of the textInput underline.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="bluronsubmit"></a><span class="platform">ios</span>blurOnSubmit <span class="propType">bool</span> <a class="hash-link" href="undefined#bluronsubmit">#</a></h4><div><p>If true, the text field will blur when submitted.
The default value is true for single-line fields and false for
multiline fields. Note that for multiline fields, setting blurOnSubmit
to true means that pressing return will blur the field and trigger the
onSubmitEditing event instead of inserting a newline into the field.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="clearbuttonmode"></a><span class="platform">ios</span>clearButtonMode <span class="propType">enum('never', 'while-editing', 'unless-editing', 'always')</span> <a class="hash-link" href="undefined#clearbuttonmode">#</a></h4><div><p>When the clear button should appear on the right side of the text view</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="cleartextonfocus"></a><span class="platform">ios</span>clearTextOnFocus <span class="propType">bool</span> <a class="hash-link" href="undefined#cleartextonfocus">#</a></h4><div><p>If true, clears the text field automatically when editing begins</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="enablesreturnkeyautomatically"></a><span class="platform">ios</span>enablesReturnKeyAutomatically <span class="propType">bool</span> <a class="hash-link" href="undefined#enablesreturnkeyautomatically">#</a></h4><div><p>If true, the keyboard disables the return key when there is no text and
automatically enables it when there is text. The default value is false.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="keyboardappearance"></a><span class="platform">ios</span>keyboardAppearance <span class="propType">enum('default', 'light', 'dark')</span> <a class="hash-link" href="undefined#keyboardappearance">#</a></h4><div><p>Determines the color of the keyboard.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onkeypress"></a><span class="platform">ios</span>onKeyPress <span class="propType">function</span> <a class="hash-link" href="undefined#onkeypress">#</a></h4><div><p>Callback that is called when a key is pressed.
Pressed key value is passed as an argument to the callback handler.
Fires before onChange callbacks.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="returnkeytype"></a><span class="platform">ios</span>returnKeyType <span class="propType">enum('default', 'go', 'google', 'join', 'next', 'route', 'search', 'send', 'yahoo', 'done', 'emergency-call')</span> <a class="hash-link" href="undefined#returnkeytype">#</a></h4><div><p>Determines how the return key should look.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="selecttextonfocus"></a><span class="platform">ios</span>selectTextOnFocus <span class="propType">bool</span> <a class="hash-link" href="undefined#selecttextonfocus">#</a></h4><div><p>If true, all text will automatically be selected on focus</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="selectionstate"></a><span class="platform">ios</span>selectionState <span class="propType">DocumentSelectionState</span> <a class="hash-link" href="undefined#selectionstate">#</a></h4><div><p>See DocumentSelectionState.js, some state that is responsible for
maintaining selection information for a document</p></div></div></div></div><div class="docs-prevnext"><a class="docs-next" href="toolbarandroid.html#content">Next →</a></div>