API Reference

usePhoneNumber(options?)

The main hook export.

import { usePhoneNumber } from '@erag/phone-number-react'

const phone = usePhoneNumber(options?)

Parameters

Parameter	Type	Default	Description
options	PhoneNumberOptions	phoneNumberData	Optional. Pass a data object to override country data, set the default country, or pre-fill the phone number.

Options shape

interface PhoneNumberOptions {
  countries?: PhoneCountry[]    // Override country list
  dialCodes?: PhoneDialCode[]   // Override dial-code list
  countryCode?: string          // Default selected country ISO2 code (e.g. 'IN')
  phone?: string                // Pre-fill phone number
}

---

Return values

countryOptions

countryOptions: PhoneCountry[]

List of all countries for rendering in a <select> or custom dropdown. Derived from bundled data or your custom data.

---

selectedCountry

selectedCountry: PhoneCountry | undefined

The currently selected country object. Use selectedCountry?.isoCode2 as the value on a controlled <select>.

---

localPhone

localPhone: string

The normalized local phone digits. Non-numeric characters are stripped and the value is truncated to the selected country's max length.

Use as the controlled value on your phone <input>.

---

callingCode

callingCode: string | null

The calling code for the selected country, for example +91 for India or +1 for the United States. Returns null if no match is found.

---

mask

mask: string

A mask pattern string for the selected country, for example XXXXX XXXXX for India. Use it as an input placeholder. No masking library is involved.

---

isValid

isValid: boolean

true when localPhone has a non-zero length that matches one of the selected country's allowed phone lengths. false otherwise.

---

handleInput

handleInput: (value: PhoneInputValue) => boolean

The unified input handler.

Accepted values:

Input type	Behavior
ChangeEvent<HTMLInputElement>	Reads event.target.value, normalizes, truncates, updates localPhone
string	Normalizes and applies the string as the new phone value
PhoneCountry object	Updates the selected country

Returns: boolean — true if the resulting phone is valid, false otherwise.

Usage on phone input:

<input value={phone.localPhone} onChange={phone.handleInput} />

Usage on country select:

onChange={(e) =>
  phone.handleInput(
    phone.countryOptions.find((c) => (c.isoCode2 ?? c.key) === e.target.value) ?? ''
  )
}

---

Exported data

import {
  countries,        // PhoneCountry[]
  dialCodes,        // PhoneDialCode[]
  phoneNumberData,  // { countries, dialCodes }
} from '@erag/phone-number-react'