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

flags​

Custom flag URLs array or a custom flag component

  • Type: CustomFlagImage[] | ComponentType
  • 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;
}