Phone Input Components

/**
 * Full-featured phone input component with country selection dropdown
 * Handles automatic formatting, validation, and country detection
 */
interface Props<InputComponentProps> extends React.InputHTMLAttributes<HTMLInputElement> {
  /** Phone number value in E.164 format (e.g., "+12133734253") */
  value?: string;
  /** Called when phone number changes, receives E.164 formatted value or undefined */
  onChange(value?: string): void;
  /** Default country to pre-select (two-letter country code) */
  defaultCountry?: Country;
  /** List of countries to show in dropdown (default: all supported countries) */
  countries?: Country[];
  /** Localization labels for countries and UI elements */
  labels?: Labels;
  /** Array of locale strings for internationalization */
  locales?: string | string[];
  /** Base URL for flag images */
  flagUrl?: string;
  /** Custom flag components */
  flags?: Flags;
  /** Custom flag component renderer */
  flagComponent?: (props: FlagProps) => JSX.Element;
  /** Add "International" option to country dropdown */
  addInternationalOption?: boolean;
  /** Icon component for international option */
  internationalIcon?: React.ElementType;
  /** Custom ordering for country options */
  countryOptionsOrder?: ('XX' | '🌐' | '|' | '...' | '…' | Country)[];
  /** Custom country select component */
  countrySelectComponent?: React.ElementType;
  /** Props to pass to country select component */
  countrySelectProps?: object;
  /** Custom input component */
  inputComponent?: React.ElementType;
  /** Props to pass to phone number input */
  numberInputProps?: object;
  /** Custom container component */
  containerComponent?: React.ElementType;
  /** Props to pass to container component */
  containerComponentProps?: object;
  /** Enable smart caret positioning during input */
  smartCaret?: boolean;
  /** Force international format display */
  international?: boolean;
  /** Limit input length based on country format */
  limitMaxLength?: boolean;
  /** Allow editing of country calling code */
  countryCallingCodeEditable?: boolean;
  /** Called when country selection changes */
  onCountryChange?(country?: Country): void;
  /** Focus input when country is selected */
  focusInputOnCountrySelection?: boolean;
  /** Initial value format preference */
  initialValueFormat?: 'national';
  /** CSS class name */
  className?: string;
  /** Inline styles */
  style?: object;
  /** Form properties */
  disabled?: boolean;
  readOnly?: boolean;
  autoComplete?: string;
  /** Event handlers */
  onFocus?(event: React.FocusEvent<HTMLElement>): void;
  onBlur?(event: React.FocusEvent<HTMLElement>): void;
}

declare const PhoneInputWithCountrySelect: React.ComponentClass<Props<DefaultInputComponentProps>>;

import React, { useState } from "react";
import PhoneInput from "react-phone-number-input";
import "react-phone-number-input/style.css";

// Basic usage
function BasicExample() {
  const [value, setValue] = useState();
  return (
    <PhoneInput
      placeholder="Enter phone number"
      value={value}
      onChange={setValue}
    />
  );
}

// With default country and custom styling
function StyledExample() {
  const [value, setValue] = useState();
  return (
    <PhoneInput
      placeholder="Enter phone number"
      value={value}
      onChange={setValue}
      defaultCountry="US"
      className="custom-phone-input"
      style={{ fontSize: '16px' }}
      onCountryChange={(country) => console.log('Country changed:', country)}
    />
  );
}

// Limited to specific countries
function LimitedCountriesExample() {
  const [value, setValue] = useState();
  return (
    <PhoneInput
      placeholder="Enter phone number"
      value={value}
      onChange={setValue}
      countries={['US', 'CA', 'MX']}
      defaultCountry="US"
    />
  );
}

/**
 * Core phone input component requiring manual metadata and labels
 * Use when you need custom metadata or want smaller bundle size with external metadata
 */
interface CoreProps<InputComponentProps> extends Props<InputComponentProps> {
  /** libphonenumber-js metadata object (required) */
  metadata: Metadata;
  /** Localization labels (required) */
  labels: Labels;
}

declare const PhoneInputWithCountrySelect: React.ComponentClass<CoreProps<DefaultInputComponentProps>>;

import PhoneInput from "react-phone-number-input/core";
import metadata from "libphonenumber-js/metadata.json";
import en from "react-phone-number-input/locale/en.json";

function CoreExample() {
  const [value, setValue] = useState();
  return (
    <PhoneInput
      placeholder="Enter phone number"
      value={value}
      onChange={setValue}
      metadata={metadata}
      labels={en}
      defaultCountry="US"
    />
  );
}

// Minimal bundle size
import PhoneInput from "react-phone-number-input/min";

// Maximum features
import PhoneInput from "react-phone-number-input/max";  

// Mobile-optimized
import PhoneInput from "react-phone-number-input/mobile";

interface State<Props> {
  /** Currently selected country */
  country?: Country;
  /** Filtered list of available countries */
  countries?: Country[];
  /** Last country manually selected by user */
  latestCountrySelectedByUser?: Country;
  /** Whether user has manually selected a country */
  hasUserSelectedACountry?: boolean;
  /** Current phone number value */
  value?: string;
  /** Parsed phone digits including leading + */
  phoneDigits?: string;
  /** Force rerender trigger */
  forceRerender?: object;
  /** Input focus state */
  isFocused?: boolean;
  /** Stored props for comparison */
  props: Props;
}

// onChange callback receives E.164 formatted value or undefined
onChange(value?: string): void;

// onCountryChange callback receives selected country or undefined  
onCountryChange?(country?: Country): void;

// Standard React input events
onFocus?(event: React.FocusEvent<HTMLElement>): void;
onBlur?(event: React.FocusEvent<HTMLElement>): void;

function EventHandlingExample() {
  const [value, setValue] = useState();
  const [country, setCountry] = useState();
  
  const handleChange = (phoneNumber) => {
    setValue(phoneNumber);
    console.log('Phone number:', phoneNumber); // e.g., "+12133734253"
  };
  
  const handleCountryChange = (selectedCountry) => {
    setCountry(selectedCountry);
    console.log('Country:', selectedCountry); // e.g., "US"
  };
  
  const handleFocus = (event) => {
    console.log('Input focused');
  };
  
  return (
    <PhoneInput
      value={value}
      onChange={handleChange}
      onCountryChange={handleCountryChange}
      onFocus={handleFocus}
      defaultCountry="US"
    />
  );
}

// Import the default stylesheet
import "react-phone-number-input/style.css";