0
# Phone Input Components
1

2
Full-featured React components with integrated country selection dropdowns, automatic phone number formatting, and validation capabilities. These components provide the complete user experience for international phone number input.
3

4
## Capabilities
5

6
### Main Phone Input Component
7

8
The primary component with country selection dropdown and comprehensive features.
9

10
```typescript { .api }
11
/**
12
 * Full-featured phone input component with country selection dropdown
13
 * Handles automatic formatting, validation, and country detection
14
 */
15
interface Props<InputComponentProps> extends React.InputHTMLAttributes<HTMLInputElement> {
16
  /** Phone number value in E.164 format (e.g., "+12133734253") */
17
  value?: string;
18
  /** Called when phone number changes, receives E.164 formatted value or undefined */
19
  onChange(value?: string): void;
20
  /** Default country to pre-select (two-letter country code) */
21
  defaultCountry?: Country;
22
  /** List of countries to show in dropdown (default: all supported countries) */
23
  countries?: Country[];
24
  /** Localization labels for countries and UI elements */
25
  labels?: Labels;
26
  /** Array of locale strings for internationalization */
27
  locales?: string | string[];
28
  /** Base URL for flag images */
29
  flagUrl?: string;
30
  /** Custom flag components */
31
  flags?: Flags;
32
  /** Custom flag component renderer */
33
  flagComponent?: (props: FlagProps) => JSX.Element;
34
  /** Add "International" option to country dropdown */
35
  addInternationalOption?: boolean;
36
  /** Icon component for international option */
37
  internationalIcon?: React.ElementType;
38
  /** Custom ordering for country options */
39
  countryOptionsOrder?: ('XX' | '🌐' | '|' | '...' | '…' | Country)[];
40
  /** Custom country select component */
41
  countrySelectComponent?: React.ElementType;
42
  /** Props to pass to country select component */
43
  countrySelectProps?: object;
44
  /** Custom input component */
45
  inputComponent?: React.ElementType;
46
  /** Props to pass to phone number input */
47
  numberInputProps?: object;
48
  /** Custom container component */
49
  containerComponent?: React.ElementType;
50
  /** Props to pass to container component */
51
  containerComponentProps?: object;
52
  /** Enable smart caret positioning during input */
53
  smartCaret?: boolean;
54
  /** Force international format display */
55
  international?: boolean;
56
  /** Limit input length based on country format */
57
  limitMaxLength?: boolean;
58
  /** Allow editing of country calling code */
59
  countryCallingCodeEditable?: boolean;
60
  /** Called when country selection changes */
61
  onCountryChange?(country?: Country): void;
62
  /** Focus input when country is selected */
63
  focusInputOnCountrySelection?: boolean;
64
  /** Initial value format preference */
65
  initialValueFormat?: 'national';
66
  /** CSS class name */
67
  className?: string;
68
  /** Inline styles */
69
  style?: object;
70
  /** Form properties */
71
  disabled?: boolean;
72
  readOnly?: boolean;
73
  autoComplete?: string;
74
  /** Event handlers */
75
  onFocus?(event: React.FocusEvent<HTMLElement>): void;
76
  onBlur?(event: React.FocusEvent<HTMLElement>): void;
77
}
78

79
declare const PhoneInputWithCountrySelect: React.ComponentClass<Props<DefaultInputComponentProps>>;
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
import React, { useState } from "react";
86
import PhoneInput from "react-phone-number-input";
87
import "react-phone-number-input/style.css";
88

89
// Basic usage
90
function BasicExample() {
91
  const [value, setValue] = useState();
92
  return (
93
    <PhoneInput
94
      placeholder="Enter phone number"
95
      value={value}
96
      onChange={setValue}
97
    />
98
  );
99
}
100

101
// With default country and custom styling
102
function StyledExample() {
103
  const [value, setValue] = useState();
104
  return (
105
    <PhoneInput
106
      placeholder="Enter phone number"
107
      value={value}
108
      onChange={setValue}
109
      defaultCountry="US"
110
      className="custom-phone-input"
111
      style={{ fontSize: '16px' }}
112
      onCountryChange={(country) => console.log('Country changed:', country)}
113
    />
114
  );
115
}
116

117
// Limited to specific countries
118
function LimitedCountriesExample() {
119
  const [value, setValue] = useState();
120
  return (
121
    <PhoneInput
122
      placeholder="Enter phone number"
123
      value={value}
124
      onChange={setValue}
125
      countries={['US', 'CA', 'MX']}
126
      defaultCountry="US"
127
    />
128
  );
129
}
130
```
131

132
### Core Phone Input Component
133

134
Core version that requires manual metadata and labels parameters.
135

136
```typescript { .api }
137
/**
138
 * Core phone input component requiring manual metadata and labels
139
 * Use when you need custom metadata or want smaller bundle size with external metadata
140
 */
141
interface CoreProps<InputComponentProps> extends Props<InputComponentProps> {
142
  /** libphonenumber-js metadata object (required) */
143
  metadata: Metadata;
144
  /** Localization labels (required) */
145
  labels: Labels;
146
}
147

148
declare const PhoneInputWithCountrySelect: React.ComponentClass<CoreProps<DefaultInputComponentProps>>;
149
```
150

151
**Usage Example:**
152

153
```typescript
154
import PhoneInput from "react-phone-number-input/core";
155
import metadata from "libphonenumber-js/metadata.json";
156
import en from "react-phone-number-input/locale/en.json";
157

158
function CoreExample() {
159
  const [value, setValue] = useState();
160
  return (
161
    <PhoneInput
162
      placeholder="Enter phone number"
163
      value={value}
164
      onChange={setValue}
165
      metadata={metadata}
166
      labels={en}
167
      defaultCountry="US"
168
    />
169
  );
170
}
171
```
172

173
### Bundle Variants
174

175
Different bundle size variants with the same API as the main component.
176

177
```typescript { .api }
178
// Minimal bundle size
179
import PhoneInput from "react-phone-number-input/min";
180

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

184
// Mobile-optimized
185
import PhoneInput from "react-phone-number-input/mobile";
186
```
187

188
All variants export the same component interface as the main PhoneInputWithCountrySelect component.
189

190
### Component State
191

192
The phone input components maintain internal state for country selection and formatting.
193

194
```typescript { .api }
195
interface State<Props> {
196
  /** Currently selected country */
197
  country?: Country;
198
  /** Filtered list of available countries */
199
  countries?: Country[];
200
  /** Last country manually selected by user */
201
  latestCountrySelectedByUser?: Country;
202
  /** Whether user has manually selected a country */
203
  hasUserSelectedACountry?: boolean;
204
  /** Current phone number value */
205
  value?: string;
206
  /** Parsed phone digits including leading + */
207
  phoneDigits?: string;
208
  /** Force rerender trigger */
209
  forceRerender?: object;
210
  /** Input focus state */
211
  isFocused?: boolean;
212
  /** Stored props for comparison */
213
  props: Props;
214
}
215
```
216

217
### Event Handling
218

219
The components provide comprehensive event handling for user interactions.
220

221
```typescript { .api }
222
// onChange callback receives E.164 formatted value or undefined
223
onChange(value?: string): void;
224

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

228
// Standard React input events
229
onFocus?(event: React.FocusEvent<HTMLElement>): void;
230
onBlur?(event: React.FocusEvent<HTMLElement>): void;
231
```
232

233
**Event Handling Examples:**
234

235
```typescript
236
function EventHandlingExample() {
237
  const [value, setValue] = useState();
238
  const [country, setCountry] = useState();
239
  
240
  const handleChange = (phoneNumber) => {
241
    setValue(phoneNumber);
242
    console.log('Phone number:', phoneNumber); // e.g., "+12133734253"
243
  };
244
  
245
  const handleCountryChange = (selectedCountry) => {
246
    setCountry(selectedCountry);
247
    console.log('Country:', selectedCountry); // e.g., "US"
248
  };
249
  
250
  const handleFocus = (event) => {
251
    console.log('Input focused');
252
  };
253
  
254
  return (
255
    <PhoneInput
256
      value={value}
257
      onChange={handleChange}
258
      onCountryChange={handleCountryChange}
259
      onFocus={handleFocus}
260
      defaultCountry="US"
261
    />
262
  );
263
}
264
```
265

266
### CSS Styling
267

268
Phone input components require CSS styling for proper display.
269

270
```typescript { .api }
271
// Import the default stylesheet
272
import "react-phone-number-input/style.css";
273
```
274

275
The stylesheet provides:
276
- `.PhoneInput` - Base component styles
277
- `.PhoneInput--focus` - Focus state styles  
278
- `.PhoneInput--disabled` - Disabled state styles
279
- `.PhoneInput--readOnly` - Read-only state styles
280
- CSS custom properties for customization (e.g., `--PhoneInputCountryFlag-height`)
281

282
### Error Handling
283

284
Components handle various error conditions gracefully:
285

286
- Invalid phone numbers return `undefined` in onChange
287
- Unsupported countries are filtered from country lists
288
- Invalid metadata gracefully falls back to minimal functionality
289
- Missing labels show country codes as fallbacks