PhoneInput

A phone number field: the Input's box with a country segment at its start (the chosen country's flag and a caret, which open a list of countries with their names and dial codes) and that country's dial code inline before the number.
The number and the country are each controlled (value / country) or self-managed (defaultValue / defaultCountry), the segment defaults to the kit's curated PHONE_COUNTRIES list (pass countries for a full or localized one), and the number field asks for the phone keypad. Pass label (and required) to name it; error paints the whole box, segment included, and Field delegates its label, required mark and error into it. The required star is decorative: a screen reader hears the number field as required, from aria-required on the web and from its name ("Phone number, required") on iOS and Android. On iOS the field is drawn to the iOS input-field reference: the white box, the flag and gray caret segment with its state-coloured divider, the dial code in the placeholder gray.
In glass mode the country list is a dense-layer glass card under the box; the box, its segment and its number stay in place. A pick commits the country and returns focus to the number at once, and a field that becomes disabled or read-only while the list is open closes it. Solid mode paints the skin's own list.
Phone number
+1
iOS
Phone number
+1
Android
Phone number
+1
Web
tsx
<PhoneInput label="Phone number" placeholder="Add your phone number" />

Props

PhoneEntry

Prop
Description
autoFocus
boolean
If true, focuses the input on componentDidMount. The default value is false.
defaultValue
string
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.
maxLength
number
Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.
onBlur
((e: BlurEvent) => void)
Callback that is called when the text input is blurred Note: If you are trying to find the last value of TextInput, you can use the `onEndEditing` event, which is fired upon completion of editing.
onFocus
((e: FocusEvent) => void)
Callback that is called when the text input is focused
onSubmitEditing
((e: TextInputSubmitEditingEvent) => void)
Callback that is called when the text input's submit button is pressed.
onKeyPress
((e: TextInputKeyPressEvent) => 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. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.
returnKeyType
ReturnKeyTypeOptions
enum('default', 'go', 'google', 'join', 'next', 'route', 'search', 'send', 'yahoo', 'done', 'emergency-call') Determines how the return key should look.
testID
string
Used to locate this view in end-to-end tests

PhoneInput

Prop
Description
value
string
The national number typed so far (controlled). Omit and use `defaultValue` for uncontrolled use.
onChangeText
(text: string) => void
Called with the new number on each keystroke.
countries
readonly PhoneCountry[]
The countries the segment offers, in the order shown. Defaults to the kit's curated `PHONE_COUNTRIES` list; pass a full, localized, or reordered list.
country
string
The selected country's ISO alpha-2 code (controlled). Omit and use `defaultCountry`.
defaultCountry
string
Initial country code for uncontrolled use. Defaults to "US" when the list has it, else the first row.
onCountryChange
(code: string) => void
Called with the chosen country's code when a row is picked (both modes).
placeholder
string
Placeholder shown while the number is empty.
label
string
The field's persistent label, rendered above the box on every platform (a grouped field never floats its label). It is the number field's programmatic name, and Field delegates its label into it.
required
boolean
Marks the field as required: a destructive "*" after the label (decorative, never in the accessible name), and the number field announced as required, through aria-required on the web and with the word in its name ("Phone number, required") on iOS and Android.
error
boolean
State (orthogonal). `error` (alias `invalid`) flags a validation problem.
invalid
boolean
State (orthogonal). `error` (alias `invalid`) flags a validation problem.
disabled
boolean
State (orthogonal). `error` (alias `invalid`) flags a validation problem.
readOnly
boolean
Read-only: shows the number but blocks editing and the country list.
small
boolean
Size (pick one; default is the medium field).
large
boolean
Size (pick one; default is the medium field).
accessibilityLabel
string
Accessible name for the number field when there is no `label`.
aria-describedby
string
ID of the helper/error text that describes the field (its `nativeID`).
style
LayoutStyle
Composition within a parent only, never a restyle hook and never a width: the parent layout container provides the bounds.
xxxs
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
xxs
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
xs
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
sm
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
md
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
lg
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
xl
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
xxl
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
xxxl
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
wide
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
wider
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
widest
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
page
boolean
Measure (pick one; omit to take the parent's bounds). Caps the component at a step of the width scale, centered in its column; `start` pins it to the leading edge.
start
boolean
Pin a capped component to the leading edge instead of centering it in its column.
autoFocus
boolean
If true, focuses the input on componentDidMount. The default value is false.
defaultValue
string
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.
maxLength
number
Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.
onBlur
((e: BlurEvent) => void)
Callback that is called when the text input is blurred Note: If you are trying to find the last value of TextInput, you can use the `onEndEditing` event, which is fired upon completion of editing.
onFocus
((e: FocusEvent) => void)
Callback that is called when the text input is focused
onSubmitEditing
((e: TextInputSubmitEditingEvent) => void)
Callback that is called when the text input's submit button is pressed.
onKeyPress
((e: TextInputKeyPressEvent) => 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. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.
returnKeyType
ReturnKeyTypeOptions
enum('default', 'go', 'google', 'join', 'next', 'route', 'search', 'send', 'yahoo', 'done', 'emergency-call') Determines how the return key should look.
testID
string
Used to locate this view in end-to-end tests
ref
React.Ref<RNTextInput>
Ref to the underlying React Native host. Supports object refs and callback refs; native methods follow the platform's behavior.

Do & Don’t

The country segment

Don’t
Phone number
A plain Input makes the user type the prefix, and nothing tells the app which country the digits belong to.
Do
Phone number
+1
Let the segment carry the country so the number stays national and the dial code is never typed twice.

Errors

Don’t
Phone number
+1
Invalid phone number.
A loose red caption beside a neutral box reads as unfinished, and a screen reader never hears it with the field.
Do
Phone number
+1
Wrap the field in a Field so the message sits under the box and the box, segment included, paints the error border.
← MediaObject
StackedList →