NitroInput props
NitroInput takes every View prop (style, testID, accessibilityLabel, …) plus the ones below. All are optional.
A test in the package fails when this page misses a prop the component declares, so what is listed here is what the component takes. Every entry links to itself.
Text and value
valuestringThe text to show (controlled). The native side formats and shows what the user types on its own; the prop is applied when it changes to something other than what the field already shows, so echoing onChangeText back into state never fights the user. A value carrying a stale mostRecentEventCount is ignored, as TextInput ignores it.
defaultValuestringThe initial text (uncontrolled).
Shown while the field is empty. With transition="reflow" the first character reflows it away. In 'number' mode '0' reads well.
Colour of the placeholder.
'text' mode: the most characters accepted.
Whether the user can edit the field.
Alias of editable={false}, as in React Native.
Mode
One prop picks how the field edits. It is separate from inputMode and keyboardType, which only pick the keyboard. See An amount field and A masked field.
'text' is a plain field. 'number' formats natively as you type: grouping separators, one decimal separator, up to fractionDigits decimals, a currency prefix / suffix; the value comes out of onChangeValue and getValue(). 'mask' applies the fixed pattern in mask.
Number mode
Most digits allowed after the decimal separator; a keystroke past it is rejected. 0 disables the decimal.
Most integer digits accepted.
Inserted between every three integer digits. '' disables grouping.
Placed between integer and fraction digits. Whatever the keyboard's decimal key produces (. or ,) is accepted as it.
Where a negative amount's sign sits relative to prefix: -$1,234.56, or $-1,234.56 with 'afterAffix'. Only the reflow honours it; a plain field's affixes are accessory views outside the text, so it is always 'afterAffix' there. See Negative amounts.
Mask mode
The pattern, e.g. '+1 ([000]) [000]-[0000]'. [0] mandatory digit, [9] optional digit, [A] mandatory letter, [a] optional letter, [_] mandatory alphanumeric, [-] optional alphanumeric, […] an unbounded run of the preceding type. {…} is a fixed block whose characters count towards the extracted value; a literal outside brackets is shown but not extracted. \\ escapes. An invalid pattern leaves the field unmasked rather than breaking it.
Your own slot characters beyond the built-in ones: the character that stands for the slot in the mask, and every character it accepts.
Fill in constants as the caret reaches them. Only with the caret at the end, so editing mid-value does not fight you.
Backspace walks back over autocompleted constants.
Keep the rest of the placeholder visible, greyed, after what has been typed: with placeholder="1234 5678 9012", typing 12345 shows 1234 5 and then 678 9012. Without a placeholder the mask itself is shown, its empty slots as maskSlotPlaceholder: +1 (212) ___-____. When one of maskAffinityFormats has taken over, its own tail is shown, since the placeholder was written for mask.
The character each empty slot shows in the kept placeholder and in onChangeMask's tail. Empty: the slot's own notation character (0, a, -).
More patterns the text may take, e.g. the Amex 4-6-5 grouping beside a 4-4-4-4 mask: ['{34}[00] [000000] [00000]', '{37}[00] [000000] [00000]']. Every edit is masked with each, and the best by maskAffinityStrategy is kept. mask wins ties; once another format is showing, it keeps a tie too, so the field does not flip back and forth as you type.
maskAffinityStrategy'wholeString' | 'prefix' | 'capacity' | 'extractedValueCapacity'Default 'wholeString'How the best of maskAffinityFormats is chosen: the format that accepts the most characters and inserts the fewest, the one whose output starts most like what was typed, or the fullest format that still holds all of the text / all of its value characters.
Uppercase or lowercase letters as they are typed or pasted, without moving the caret: a BIC, an IBAN or a licence plate typed in lowercase comes out right.
Characters replaced before masking, one character each: { 'С': 'C' } turns a Cyrillic look-alike into a Latin letter, { ',': '.' } lets a comma through to a dot-decimal mask. An empty replacement drops the character.
Affixes
Static text around the field's text, drawn at their own sizes. See An amount field.
Drawn before the text, e.g. '$'.
Drawn after the text, e.g. ' USD'.
Font size of prefix, e.g. a smaller currency symbol.
Font size of suffix.
How prefix and suffix line up with the text: 'top' pins glyph tops, 'bottom' the bottom of the ink, 'baseline' shares the baseline, 'center' centres.
Alignment of prefix only.
Alignment of suffix only.
Points added after every glyph, like Text's letterSpacing (negative tightens). A smaller prefix or suffix gets it in proportion to its size.
Points between the prefix and the text, and between the text and the suffix, in place of the letter spacing there.
Points an affix is moved down after its alignment places it (negative: up), for a symbol that sits a little off every preset.
formatNumberFormatA NumberFormat the amount follows: its prefix and suffix (the currency where the locale puts it), grouping and decimal separators, fraction digits and where the sign goes. Sets mode to 'number' unless it is given; the individual props override what it says.
Frame and label
An outlined or filled box with a floating label, drawn natively. See Frames.
'outlined' strokes a rounded rectangle notched around the floating label; the notch is a real hole in the path, so whatever is behind the field shows through. 'filled' tints the box. 'none' leaves the border to style.
The floating label. Needs a variant other than 'none'. Also the field's accessible name when nothing else supplies one.
'float' sits inline while the field is empty and unfocused and floats once it is focused or has text; 'always' stays floated.
Label colour at rest.
Label colour while focused.
Label size when floated, in points.
Outline colour.
Outline colour while focused.
Outline width in points, doubled while focused.
Corner radius of the frame.
fillColorColorValue'filled': the box tint.
Typography
Resolved the way Text resolves its style.
Font size in points.
Font weight, as Text's.
Font family, as Text's; bundled and expo-font fonts work.
Text colour.
Height of the line box in points, in the CSS sense: the total height a line occupies. Unlike TextInput, a line height tighter than the font is centred correctly too, and it applies to single-line and reflowing fields as well as wrapped ones.
Scale the fonts with the system text size, like Text. Off by default so amounts keep their design size.
Upper bound for allowFontScaling, e.g. 1.3. 0 is no cap.
Size and alignment
Whether the field sizes itself to its content. false takes its width from the parent the way a TextInput does, which is what makes it a drop-in. true always sizes to content. 'auto' infers it: on unless style gives a width or flex, which lets an amount grow as digits arrive, and is the default with transition="reflow".
Where the text sits when the view is wider than it. 'auto' is the start edge of the layout direction, as TextInput; 'left' and 'right' are absolute. See Right-to-left.
Scale the text down when it is wider than the view (give the view a fixed width in style), and back up when it fits again.
Smallest scale adjustsFontSizeToFit may apply, 0–1.
Multiline
A wrapping field is drawn by the system view and is always 'text' mode: transition="reflow", a non-text mode and the affixes are ignored alongside it, with one warning each in development. See Multiline.
Let the text wrap onto more than one line. The return key inserts a line break unless submitBehavior says otherwise.
numberOfLinesnumberLines tall before it scrolls. Omit to grow with the content.
rowsnumberAlias of numberOfLines, matching TextInput.
Where the text sits in the box; 'auto' is the top.
Whether it scrolls once the text outgrows it.
Keyboard and return key
keyboardType'default' | 'number-pad' | 'decimal-pad' | 'numeric' | 'email-address' | 'phone-pad' | 'url' | 'ascii-capable' | 'numbers-and-punctuation'Default by modeKeyboard to show. 'number' mode defaults to 'decimal-pad' ('number-pad' with fractionDigits={0}), the others to 'default'.
inputMode'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'React Native's alias for keyboardType, following the HTML attribute and mapped with React Native's own table. Ignored when keyboardType is given. 'none' focuses without a keyboard, as in TextInput.
Label of the return key.
enterKeyHint'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send'React Native's alias for returnKeyType, following the HTML attribute. Ignored when returnKeyType is given.
iOS: a light or dark keyboard; 'default' follows the system appearance.
Disables the return key until the field has text.
false keeps focus and the caret without the soft keyboard, for a field driven by an in-app keypad.
submitBehavior'blurAndSubmit' | 'submit' | 'newline'Default 'blurAndSubmit', 'newline' when multilineWhat the return key does: 'blurAndSubmit' fires onSubmitEditing and dismisses the keyboard; 'submit' fires it and keeps focus, so a form can move to the next field itself; 'newline' inserts a line break (multiline only). The defaults are TextInput's.
blurOnSubmitbooleanDeprecated alias of submitBehavior, resolved as TextInput resolves it: false means 'submit' on a single-line field, true means 'blurAndSubmit' on a multiline one. Ignored when submitBehavior is given.
Focus the field when it mounts. Taken synchronously as soon as the view has a window, so on iOS a screen pushed over a focused field swaps the keyboard in place instead of dismissing and re-presenting it.
Editing behaviour
Auto-capitalisation in 'text' mode.
Auto-correction in 'text' mode.
Spell checking in 'text' mode.
Draws bullets and turns off autocorrect; the field keeps the real text for editing and autofill.
iOS textContentType, the autofill kind: 'username', 'password', 'oneTimeCode', …
The cross-platform autofill hint, as TextInput's. Used as textContentType on iOS when that is not set.
Select all the text when the field gains focus.
Empty the field when it gains focus.
Hides the Cut / Copy / Paste menu.
Caret and selection
Caret colour.
Selection highlight colour.
Hides the caret.
selection{ start: number; end?: number }The caret or selection to apply, in code points into the (formatted) text. onSelectionChange reports moves in the same units.
The reflow
The opt-in glyph animation: every edit reflows from the old text to the new one. See The reflow.
How the text changes. 'none' draws it the instant it changes: this is a text field first, and a TextInput does not animate its characters. 'reflow' runs the glyph engine, so characters that stay glide to their new place, new ones slide or fade in and removed ones leave alongside their neighbours. A multiline field is always 'none'.
Duration in ms of the reflow played on every change. 0 snaps.
Timing curve of the reflow. 'expo' is Torph's cubic-bezier(0.19, 1, 0.22, 1).
Overshoot of the 'spring' easing, 0–1.
How characters enter and leave. 'auto': digits and separators slide through the line box (digits from above, separators from below), other characters fade and scale.
Worklets
With react-native-worklets installed, work can run on the UI thread inside the native edit, before a frame is drawn. See Worklets.
transformNitroInputTransformA worklet that rewrites the text after every edit, synchronously on the UI thread: masks, custom formats, anything JS can express. It receives the edited text, the previous text and both selections (code point offsets) and returns the new text and optionally where the caret goes; null keeps the edit. In 'number' mode it runs after the native formatter. Create it once (module scope or useCallback): a new function re-registers the worklet.
Any event handler below marked 'worklet' runs on the UI thread instead of the JS one.
Events
Every event is a superset of TextInput's: nativeEvent carries React Native's fields under React Native's names, so a handler written for a TextInput works unchanged, and the same fields are repeated at the top level, so ({ text }) => … reads better than (e) => e.nativeEvent.text.
onChangeText(text: string) => voidAfter every edit, with the field's (formatted) text. Marked 'worklet', it runs on the UI thread and can write shared values before the next frame.
onChange({ nativeEvent: { text, eventCount, target } }) => voidReact Native's other change callback, fired alongside onChangeText with the same text. eventCount is the native edit counter, as in TextInput.
onChangeValue(value: number) => void'number' mode: after every edit, with the numeric value; NaN when empty. A 'worklet' runs on the UI thread.
onChangeMask(formatted, extracted, tailPlaceholder, complete) => void'mask' mode: after every edit, with the masked text, the characters the user contributed, what is still missing, and whether every mandatory slot is filled.
onFocus(event: NitroInputFocusEvent) => voidFocused. The event carries text, eventCount and target.
onBlur(event: NitroInputFocusEvent) => voidBlurred. Same event as onFocus.
onSubmitEditing(event: NitroInputTextEvent) => voidThe return key was pressed.
onEndEditing(event: NitroInputTextEvent) => voidEditing finished: focus lost or the keyboard dismissed, as TextInput's.
onSelectionChange(event: NitroInputSelectionEvent) => voidThe caret or selection moved. selection, start and end are code points.
onKeyPress(event: NitroInputKeyPressEvent) => voidA key was pressed, before the text changes: the character, 'Backspace' or 'Enter'.
onNativeRef(ref: NitroInputRef) => voidReceives the native Nitro object once the view is mounted.
Accessibility and identity
The system field is the accessibility element, with the formatted text as its value ($1,234.50 USD reads as such). See Working with React Native.
The field's name for VoiceOver and TalkBack, forwarded to the system field. aria-label wins over the older spelling, as in TextInput. Without either, label is used.
aria-labelledbystringForwarded as accessibilityLabelledBy.
Fold into accessibilityState, as on any view.
testID, nativeID, idstringForwarded to the system field, the element e2e tools find. id wins over nativeID, as in TextInput.
styleViewStyleThe host view's style. Width comes from it unless autoWidth says otherwise; direction: 'rtl' flips a single field.
Methods (ref)
The handle queues a call made before the native view exists and replays it once mounted, so focus() in an effect on mount works.
| Method | Description |
|---|---|
focus() | Focuses the field. |
blur() | Blurs it. |
clear() | Empties the field; with transition="reflow" the characters reflow away. |
setText(text) | Replaces the text (formatted in 'number' mode), caret at the end. |
setValue(value) | 'number' mode: shows value formatted; NaN empties the field. |
getText() | The field's current (formatted) text. |
getValue() | 'number' mode: the numeric value, NaN when empty. |
isFocused() | Whether the field has focus. |
setSelection(start, end?) | Moves the caret or selection; code points into the (formatted) text. |
native | The native Nitro object, or null before mount. |
Hook
useNitroInputState(useSharedValue) returns the field's text, value, focused and selection as shared values, plus the worklet handlers to spread onto the field that keep them current. See the field's state as shared values.