PhoneInputProps

Properties

aria-describedby?

optional aria-describedby?: string;

ids of external error/help text.

aria-label?

optional aria-label?: string;

Accessible name, when there is no visible text to point label at. Wins over label if both are given.

autoFocus?

optional autoFocus?: boolean;

Focus the field on mount.

Default

false

className?

optional className?: string;

countries?

optional 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?

optional country?: string;

Controlled selected country, ISO 3166-1 alpha-2.

countryLabel?

optional countryLabel?: string;

Accessible name for the country select.

Default

'Country'

defaultCountry?

optional defaultCountry?: string;

Initial country for the uncontrolled case.

Default

'US'

defaultValue?

optional defaultValue?: string;

Uncontrolled initial value in E.164. Ignored when value is provided.

dir?

optional dir?: "ltr" | "rtl";

Writing direction for the field. Inherited from the document when unset.

disabled?

optional disabled?: boolean;

hideCountrySelect?

optional hideCountrySelect?: boolean;

Drop the country select and require numbers to be typed in +… form.

id?

optional id?: string;

Base id; the input, select and hidden field derive ids from it.

invalid?

optional invalid?: boolean;

Sets aria-invalid and data-invalid.

label?

optional 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?

optional locale?: string;

BCP 47 tag for country names.

Default

the runtime's locale

maxLength?

optional 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

name?

optional name?: string;

Emits a hidden input carrying the E.164 value, readable by a native <form>.

onBlur?

optional onBlur?: (event) => void;

Fires when focus leaves the whole field, not when moving between its parts.

Parameters

Parameter	Type
`event`	`FocusEvent`<`HTMLElement`>

Returns

void

onChange?

optional onChange?: (value, details) => void;

Fires whenever the number changes, with the E.164 string and the details.

Parameters

Parameter	Type
`value`	`string`
`details`	`PhoneDetails`

Returns

void

onCountryChange?

optional onCountryChange?: (iso2) => void;

Parameters

Parameter	Type
`iso2`	`string`

Returns

void

onFocus?

optional onFocus?: (event) => void;

Parameters

Parameter	Type
`event`	`FocusEvent`<`HTMLElement`>

Returns

void

onWarn?

optional 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

Parameter	Type
`warning`	`PhoneWarning`

Returns

void

placeholder?

optional placeholder?: string;

readOnly?

optional readOnly?: boolean;

renderCountry?

optional renderCountry?: (state) => ReactNode;

Custom option contents.

Parameters

Parameter	Type
`state`	`PhoneCountryState`

Returns

ReactNode

Default

flag, name and calling code

required?

optional required?: boolean;

showValidity?

optional 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

false

style?

optional style?: CSSProperties;

validityLabel?

optional validityLabel?: (state) => ReactNode;

Custom text for the showValidity message. Return '' to say nothing.

Parameters

Parameter	Type
`state`	{ `country`: \| `Country` \| `undefined`; `details`: `PhoneDetails`; `possible`: `boolean`; }
`state.country`	\| `Country` \| `undefined`
`state.details`	`PhoneDetails`
`state.possible`	`boolean`

Returns

ReactNode

value?

optional 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.