📱 Pro Phone Input Widget

A highly flexible and responsive React component for international phone number input. It combines a country selector, dial code display, and number input field into a single, cohesive component with robust client-side validation logic.

✨ Features

Customizable: Accepts all standard HTML input attributes (name, id, data-*, etc.).

Structured Output: Provides the country object and raw number in a clear object format.

Imperative Validation: Check validation state on form submission via a React ref.

Responsive UI: Styled with Tailwind CSS principles for a modern, mobile-friendly experience.

✨ Prerequisite

You have to download flags file for country media flags and add it to public directory of your project from here.


🚀 Installation

To use the component in your project, install it via npm or yarn:

npm install pro-phone-input-widget

or

yarn add pro-phone-input-widget



🛠️ Usage Example

check through Demo
or
from github here





📋 API & Props

The component accepts standard HTML input attributes (name, id, onBlur, etc.) in addition to the following custom props:

initialValue (string, Default: ''): The initial number to display in the input field (without the dial code).

defaultCountry (Country, Default: Determined by defaultCountryCode or US): NEW: Explicitly sets the starting country using a Country object.

defaultCountryCode (string, Default: 'US'): The ISO 2-digit code for the default country (if defaultCountry object is not provided).

customErrorMessage (string, Default: 'Invalid phone number format.'): The message shown below the input when validation fails.

disableNativeName (boolean, Default: false): If true, hides the native country name in the dropdown list.

allowedCountries (string[], Default: undefined): Array of ISO 2-digit codes to restrict the country list.

onChange ((number, country, isValid) => void, Default: undefined): Callback for continuous value change updates.



💅 Customizing Appearance (CSS Classes)

All internal elements use unique CSS class names, allowing you to easily target and override styles using standard CSS or a framework like Tailwind CSS (which is used internally).

Outer Container (Class: phone-input-container): The main wrapper element, which holds the input and selector.

Country Selector Button (Class: phone-input-selector): The clickable div containing the flag and dial code.

Flag Emoji/Image (Class: phone-input-flag): The element displaying the flag in the selector button.

Dial Code Text (Class: phone-input-dial-code): The text displaying the country's dial code (e.g., +1).

Main Number Input (Class: phone-input-field): The primary element.

Dropdown Wrapper (Class: phone-input-dropdown): The container for the country list when open.

Search Filter Input (Class: phone-input-filter): The search input field inside the dropdown.

List Item Wrapper (Class: phone-input-list-item): The clickable container for each country in the dropdown.

Country Name Text (Class: phone-input-country-name): The full English name of the country in the list.

Native Name Text (Class: phone-input-native-name): The native name of the country in the list (if shown).

Error Message (Class: phone-input-error-message): The container for the validation error text.



📝 Data Structures

interface Country

export interface Country {
name: string; // e.g., 'United States'
nativeName: string; // e.g., 'Deutschland'
isoCode: string; // e.g., 'US'
dialCode: string; // e.g., '+1'
nsnLength: number; // Length of the national significant number
}



interface ValidationResult

This is the object returned by getValidationState() and passed to the onChange handler.

export interface ValidationResult {
fullNumber: string; // The complete E.164-like number (e.g., "+15551234567")
country: Country; // The Country object currently selected
isValid: boolean; // The validation status
number: string; // The raw national number (e.g., "5551234567")
}