PhoneInputProps
Properties
Section titled “Properties”aria-describedby?
Section titled “aria-describedby?”"aria-describedby"?: string;ids of external error/help text.
aria-label?
Section titled “aria-label?”"aria-label"?: string;Accessible name, when there is no visible text to point label at. Wins
over label if both are given.
autoFocus?
Section titled “autoFocus?”autoFocus?: boolean;Focus the field on mount.
Default
Section titled “Default”falseclassName?
Section titled “className?”className?: string;countries?
Section titled “countries?”countries?: string[];Restrict the list, in the order given. An empty array is ignored — a picker with nothing in it is not a usable field.
country?
Section titled “country?”country?: string;Controlled selected country, ISO 3166-1 alpha-2.
countryLabel?
Section titled “countryLabel?”countryLabel?: string;Accessible name for the country select.
Default
Section titled “Default”'Country'defaultCountry?
Section titled “defaultCountry?”defaultCountry?: string;Initial country for the uncontrolled case.
Default
Section titled “Default”'US'defaultValue?
Section titled “defaultValue?”defaultValue?: string;Uncontrolled initial value in E.164. Ignored when value is provided.
dir?: "ltr" | "rtl";Writing direction for the field. Inherited from the document when unset.
disabled?
Section titled “disabled?”disabled?: boolean;hideCountrySelect?
Section titled “hideCountrySelect?”hideCountrySelect?: boolean;Drop the country select and require numbers to be typed in +… form.
id?: string;Base id; the input, select and hidden field derive ids from it.
invalid?
Section titled “invalid?”invalid?: boolean;Sets aria-invalid and data-invalid.
label?
Section titled “label?”label?: ReactNode;Accessible name for the field. Not rendered — supply your own visible
<label htmlFor={${id}-input}> when the design calls for one, exactly as
every other input in the suite expects. A node is exposed through a hidden
element, since aria-label only takes a string.
locale?
Section titled “locale?”locale?: string;BCP 47 tag for country names.
Default
Section titled “Default”the runtime's localemaxLength?
Section titled “maxLength?”maxLength?: number;Longest text the field accepts, in characters.
The cap is always applied; this prop only moves it. An unbounded phone
field is a denial-of-service surface — every keystroke re-parses and
re-groups the whole contents, and a paste decides how much that is. E.164
caps a number at 15 digits, so the longest text this field can itself
produce is 21 characters (+, the calling code, and the grouped digits);
32 leaves half again as much room for the brackets, dashes and spaces
people paste, and no number written the way people write them comes close.
Values below 21, or non-finite ones, cannot bound a real number and fall
back to the default with a max-length-too-small warning.
Default
Section titled “Default”32name?: string;Emits a hidden input carrying the E.164 value, readable by a native <form>.
onBlur?
Section titled “onBlur?”onBlur?: (event) => void;Fires when focus leaves the whole field, not when moving between its parts.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
event | FocusEvent<HTMLElement> |
Returns
Section titled “Returns”void
onChange?
Section titled “onChange?”onChange?: (value, details) => void;Fires whenever the number changes, with the E.164 string and the details.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
value | string |
details | PhoneDetails |
Returns
Section titled “Returns”void
onCountryChange?
Section titled “onCountryChange?”onCountryChange?: (iso2) => void;Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
iso2 | string |
Returns
Section titled “Returns”void
onFocus?
Section titled “onFocus?”onFocus?: (event) => void;Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
event | FocusEvent<HTMLElement> |
Returns
Section titled “Returns”void
onWarn?
Section titled “onWarn?”onWarn?: (warning) => void;Called in development whenever a prop is rejected or coerced — see
PhoneWarning. When omitted, the same warnings go to console.warn.
The entire path is stripped from production builds.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
warning | PhoneWarning |
Returns
Section titled “Returns”void
placeholder?
Section titled “placeholder?”placeholder?: string;readOnly?
Section titled “readOnly?”readOnly?: boolean;renderCountry?
Section titled “renderCountry?”renderCountry?: (state) => ReactNode;Custom option contents.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
state | PhoneCountryState |
Returns
Section titled “Returns”ReactNode
Default
Section titled “Default”flag, name and calling coderequired?
Section titled “required?”required?: boolean;showValidity?
Section titled “showValidity?”showValidity?: boolean;Report, after the field has been left, whether the digits are a length the selected country actually uses. Off by default — a form that already shows its own errors does not want a second opinion inline.
This reflects possible, not full validity: it catches a typo’d or
half-typed number, not an unassigned one. See the About page.
Default
Section titled “Default”falsestyle?
Section titled “style?”style?: CSSProperties;validityLabel?
Section titled “validityLabel?”validityLabel?: (state) => ReactNode;Custom text for the showValidity message. Return '' to say nothing.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
state | { country: | Country | undefined; details: PhoneDetails; possible: boolean; } |
state.country | | Country | undefined |
state.details | PhoneDetails |
state.possible | boolean |
Returns
Section titled “Returns”ReactNode
value?
Section titled “value?”value?: string;Controlled value in E.164 ('+14155552671') or '' for empty.
One canonical format in and out — never the formatted display text, which changes with the country and would make the value a presentation detail.