Skip to main content

PhoneInput API

PhoneInput is a highly customizable phone input component.

Usage Example​

Import component

import { PhoneInput } from 'react-international-phone';

Use by providing the defaultCountry, value and onChange callback.

<PhoneInput
  defaultCountry="ua"
  value={phone}
  onChange={(phone) => setPhone(phone)}
/>

Output:

Properties​

value​

Phone value.

  • Type: string
  • Default: ""

onChange​

Callback that calls on phone change

  • Type: (phone: string, meta: { country: ParsedCountry, inputValue: string }) => void
  • Default: undefined

defaultCountry​

Default country value (iso2).

  • Type: CountryIso2
  • Default: "us"

countries​

An array of available countries to select (and guess)

  • Type: CountryData[]
  • Default: defaultCountries

preferredCountries​

An array of countries to display at the top of the dropdown list

  • Type: CountryIso2[]
  • Default: []

hideDropdown​

Hide the dropdown icon. Make country selection not accessible.

  • Type: boolean
  • Default: false

disabled​

Disable phone input and country selector.

  • Type: boolean
  • Default: false

prefix​

Prefix for phone value.

  • Type: string
  • Default: "+"

defaultMask​

This mask will apply on countries that does not have specified mask.

  • Type: string
  • Default: "............"

charAfterDialCode​

Char that renders after country dial code.

  • Type: string
  • Default: " "

historySaveDebounceMS​

Save value to history if there were not any changes in provided milliseconds timeslot. Undo/redo (ctrl+z/ctrl+shift+z) works only with values that are saved in history

  • Type: number
  • Default: 200

disableCountryGuess​

Disable country guess on value change. onCountryGuess callback would not be called.

  • Type: boolean
  • Default: false

disableDialCodePrefill​

Disable dial code prefill on initialization. Dial code prefill works only when empty phone value have been provided.

  • Type: boolean
  • Default: false

forceDialCode​

Always display the dial code. Dial code can't be removed/changed by keyboard events, but it can be changed by pasting another country phone value.

  • Type: boolean
  • Default: false

disableDialCodeAndPrefix​

Display phone value will not include passed dialCode and prefix if set to true. forceDialCode value will be ignored.

  • Type: boolean
  • Default: false

showDisabledDialCodeAndPrefix​

Show prefix and dial code between country selector and phone input. Works only when disableDialCodeAndPrefix is true

  • Type: boolean
  • Default: false

disableFocusAfterCountrySelect​

Disable auto focus on input field after country select.

  • Type: boolean
  • Default: false

disableFormatting​

Disable phone value mask formatting. All formatting characters will not be displayed, but the mask length will be preserved.

  • Type: boolean
  • Default: false

allowMaskOverflow​

Allow input to exceed the mask length. When set to true, formatting mask will apply to the part that fits within the mask capacity, and overflow digits will be appended at the end unformatted.
For example: "+123456789012", will be formatted like "+1 (234) 567-89012"

  • Type: boolean
  • Default: false

flags​

Custom flag URLs array

  • Type: CustomFlagImage[]
  • Default: undefined

inputProps​

Default input component props

  • Type: InputHTMLAttributes
  • Default: undefined
note

Input props like onFocus, onBlur, name, placeholder, disabled, required and autoFocus also supported as top-level props.
If you want add some additional attributes to the input element, you can do it using inputProps

Style properties​

PropTypeDescription
styleCSSPropertiesCustom styles for PhoneInput container
classNamestringCustom className for PhoneInput container
inputStyleCSSPropertiesCustom styles for input field
inputClassNamestringCustom className for input field
countrySelectorStylePropsCountrySelectorStylePropsStyle properties for country selector
dialCodePreviewStylePropsDialCodePreviewStylePropsStyle properties for dial code preview

CSS variables​

VariableDefault value
--react-international-phone-height36px
--react-international-phone-background-colorwhite
--react-international-phone-text-color#222
--react-international-phone-font-size13px
--react-international-phone-border-radius4px
--react-international-phone-border-colorgainsboro
--react-international-phone-disabled-background-colorwhitesmoke
--react-international-phone-disabled-text-color#666
info

You can find more styling properties and CSS variables in Subcomponents

Ref forwarding​

You can pass ref to a PhoneInput component.
Ref object refers to inner input element with some additional properties.

const PhoneWithRef = () => {
  const ref = useRef(null);
  return (
    <PhoneInput ref={ref}>;
  )
}
note

If you use typescript you should use PhoneInputRefType for as ref type:

import { PhoneInputRefType } from 'react-international-phone';
// ...
const ref = useRef<PhoneInputRefType>(null);

Ref additional properties​

In addition to the HTMLInputElement API, ref also allows you to use these methods:

setCountry​

Set some country value (works same as country selector country item click handler)

  • Type: (iso2: CountryIso2, options?: { focusOnInput: boolean }) => void

state​

State of the phone input

  • Type: { phone: string; inputValue: string; country: ParsedCountry }

ParsedCountry type​

onChange callback provides country object with ParsedCountry type:

interface ParsedCountry {
  name: string;
  iso2: CountryIso2;
  dialCode: string;
  format: FormatConfig | string | undefined;
  priority: number | undefined;
  areaCodes: string[] | undefined;
}

Parsed country object example:

{
  name: 'Ukraine';
  iso2: 'ua';
  dialCode: '380';
  format: '(..) ... .. ..';
  priority: undefined;
  areaCodes: undefined;
}