usePhoneInput

usePhoneInput is a custom hook provides full functionalities of the PhoneInput component to an existing input.

Install

To start using usePhoneInput, you can install the @react-awesome/phone-input library or you can import it directly from @react-awesome/components if you have installed it before. In your project directory, run the following command to install the dependencies:

npm i @react-awesome/phone-input

Usage

import { usePhoneInput } from '@react-awesome/phone-input'
 
const Example = () => {
  const { register } = usePhoneInput()
 
  return (
    <input
      placeholder="I have been upgraded with usePhoneInput 😎"
      {...register('use-phone-input')}
    />
  )
}

Phone Input With National Format

By default usePhoneInput has mode is set to international.

When mode is international the value will be formatted as e164.

When mode is national the country code and the + sign will be ignored. Value is formatted as national format of the current selected country.

import { usePhoneInput } from '@react-awesome/phone-input'
 
const Example = () => {
  const { register } = usePhoneInput({
    mode: 'national',
  })
 
  return (
    <input
      placeholder="I am a local phone input"
      {...register('use-phone-input')}
    />
  )
}

Phone Input With Fixed Country

usePhoneInput also accepts country prop.

When country is provided then the enterred value is formatted based on the provided country code and the country detection behaviour will be disabled.

import { usePhoneInput } from '@react-awesome/phone-input'
 
const Example = () => {
  const { register } = usePhoneInput({
    country: 'VN',
  })
 
  return (
    <input
      placeholder="I am a fixed country phone input"
      {...register('use-phone-input')}
    />
  )
}

country can also work with national format.

import { usePhoneInput } from '@react-awesome/phone-input'
 
const Example = () => {
  const { register } = usePhoneInput({
    country: 'VN',
    mode: 'national',
  })
 
  return (
    <input
      placeholder="I only accept Vietnamese phone number with national format"
      {...register('use-phone-input')}
    />
  )
}

Parameters

The usePhoneInput takes the following parameters:

value (optional)

Phone value

• Type: string
• Default: undefined

supportedCountries (optional)

Supported countries

• Type: CountryCode[]
• Default: undefined

defaultCountry (optional)

Default selected country

• Type: CountryCode
• Default: undefined

onChange (optional)

onChange handler. The callback's event could be undefined when the event is triggered when user select another country.

• Type: (ev: React.ChangeEvent<HTMLInputElement> | undefined, metadata: PhoneInputChangeMetadata) => void
• Default: () => void 0

smartCaret (optional)

Use smart caret.

• Type: boolean
• Default: true

mode (optional)

• Type: international | national
• Default: international

country (optional)

When country is provided, the country detection behavior will be disabled.

• Type: CountryCode
• Default: undefined

API

The usePhoneInput returns the following props:

inputEl

Input element.

• Type: HTMLInputElement

register

Register function returns input event handlers.

• Type: PhoneInputRegister

options

Country option list to render.

• Type: CountryCode[]

isSelectOpen

Indicator of country selector visible state.

• Type: boolean

openCountrySelect

Show the country select pane.

• Type: () => void

closeCountrySelect

Hide the country select pane.

• Type: () => void

toggleCountrySelect

Toggle the country select visible state.

• Type: () => void

selectedCountry

The current selected country.

• Type: CountryCode

phoneCode

The current selected country's calling code.

• Type: string

setSelectedCountry

Set the selected country.

• Type: (country : CounntryCode) => void

Types

PhoneInputChangeMetadata

• Type: object

isValid

• Type: boolean

isPossible

• Type: boolean

e164Value

• Type: string

country

• Type: CountryCode

phoneCode

• Type: string

formattedValue

• Type: string

isSupported

• Type: boolean

CountryCode

• Type: string