0
# React Phone Number Input
1

2
React Phone Number Input is a comprehensive international telephone number input component library for React applications. It provides full-featured components with country selection dropdowns, input-only components, and specialized variants for different use cases, all powered by libphonenumber-js for accurate parsing, validation, and formatting of international phone numbers.
3

4
## Package Information
5

6
- **Package Name**: react-phone-number-input
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install react-phone-number-input --save`
10

11
## Core Imports
12

13
The library provides multiple entry points for different use cases:
14

15
```typescript
16
// Full-featured component with country select (default)
17
import PhoneInput from "react-phone-number-input";
18
import "react-phone-number-input/style.css";
19

20
// Input-only component (no country select)  
21
import PhoneInput from "react-phone-number-input/input";
22

23
// Core versions (require metadata parameter)
24
import PhoneInput from "react-phone-number-input/core";
25
import PhoneInput from "react-phone-number-input/input-core";
26

27
// Size variants
28
import PhoneInput from "react-phone-number-input/min";
29
import PhoneInput from "react-phone-number-input/max";
30
import PhoneInput from "react-phone-number-input/mobile";
31

32
// React Hook Form integration
33
import PhoneInput from "react-phone-number-input/react-hook-form";
34

35
// React Native
36
import PhoneInput from "react-phone-number-input/react-native-input";
37

38
// Utility functions
39
import { 
40
  formatPhoneNumber, 
41
  formatPhoneNumberIntl,
42
  parsePhoneNumber,
43
  isValidPhoneNumber,
44
  getCountries,
45
  getCountryCallingCode 
46
} from "react-phone-number-input";
47

48
// Localization
49
import en from "react-phone-number-input/locale/en";
50
import de from "react-phone-number-input/locale/de";
51
// ... 25+ other locales available
52

53
// Country flags
54
import flags from "react-phone-number-input/flags";
55
```
56

57
CommonJS:
58

59
```javascript
60
const PhoneInput = require("react-phone-number-input");
61
const { formatPhoneNumber, parsePhoneNumber } = require("react-phone-number-input");
62
```
63

64
## Basic Usage
65

66
```typescript
67
import React, { useState } from "react";
68
import PhoneInput from "react-phone-number-input";
69
import "react-phone-number-input/style.css";
70

71
function MyComponent() {
72
  // Value will be in E.164 format: "+12133734253"
73
  const [value, setValue] = useState();
74
  
75
  return (
76
    <PhoneInput
77
      placeholder="Enter phone number"
78
      value={value}
79
      onChange={setValue}
80
      defaultCountry="US"
81
    />
82
  );
83
}
84
```
85

86
## Architecture
87

88
React Phone Number Input is built around several key architectural components:
89

90
- **Component Variants**: Multiple specialized components for different use cases (with/without country select, mobile-optimized, framework integrations)
91
- **Entry Point System**: Extensive package.json exports providing 15+ entry points for different bundle sizes and feature sets
92
- **Metadata System**: Built-in libphonenumber-js integration with options for custom metadata in "core" variants
93
- **Internationalization**: Complete i18n support with 25+ locale files covering country names and UI labels
94
- **Type System**: Full TypeScript support with comprehensive type definitions for all variants and props
95
- **Customization Layer**: Extensive customization options including custom input components, flag components, and styling
96

97
## Capabilities
98

99
### Phone Input Components
100

101
Full-featured React components with country selection dropdowns, automatic formatting, and validation. Perfect for user registration forms and contact information collection.
102

103
```typescript { .api }
104
interface Props<InputComponentProps> {
105
  value?: string;
106
  onChange(value?: string): void;
107
  defaultCountry?: Country;
108
  countries?: Country[];
109
  labels?: Labels;
110
  placeholder?: string;
111
  disabled?: boolean;
112
  readOnly?: boolean;
113
  onCountryChange?(country?: Country): void;
114
  // ... extensive customization options
115
}
116

117
declare const PhoneInputWithCountrySelect: React.ComponentClass<Props<DefaultInputComponentProps>>;
118
```
119

120
[Phone Input Components](./phone-input-components.md)
121

122
### Input-Only Components  
123

124
Streamlined phone number input components without country selection dropdowns. Ideal for cases where country context is predetermined or handled separately.
125

126
```typescript { .api }
127
interface Props<InputComponentProps> {
128
  value?: string;
129
  onChange(value?: string): void;
130
  country?: Country;
131
  international?: boolean;
132
  withCountryCallingCode?: boolean;
133
  defaultCountry?: Country;
134
  smartCaret?: boolean;
135
  // ... customization options
136
}
137

138
declare const PhoneInput: React.ForwardRefExoticComponent<Props<DefaultInputComponentProps>>;
139
```
140

141
[Input-Only Components](./input-components.md)
142

143
### Framework Integrations
144

145
Specialized components for popular React frameworks and libraries, providing seamless integration with existing form systems.
146

147
```typescript { .api }
148
// React Hook Form integration
149
interface ReactHookFormProps<FormValues> {
150
  name: string;
151
  control?: Control<FormValues>;
152
  rules?: object;
153
  defaultValue?: string;
154
  shouldUnregister?: boolean;
155
  // ... base component props
156
}
157

158
declare const PhoneInputWithCountrySelect: <FormValues>(props: ReactHookFormProps<FormValues>) => JSX.Element;
159
```
160

161
[Framework Integrations](./framework-integrations.md)
162

163
### Utility Functions
164

165
Comprehensive phone number parsing, formatting, and validation utilities powered by libphonenumber-js.
166

167
```typescript { .api }
168
function formatPhoneNumber(value: string): string;
169
function formatPhoneNumberIntl(value: string): string;
170
function parsePhoneNumber(input: string): PhoneNumber | undefined;
171
function isValidPhoneNumber(input: string): boolean;
172
function isPossiblePhoneNumber(input: string): boolean;
173
function getCountries(): Country[];
174
function getCountryCallingCode(country: Country): string;
175
function isSupportedCountry(country: Country): boolean;
176
```
177

178
[Utility Functions](./utility-functions.md)
179

180
### Internationalization
181

182
Complete internationalization support with locale files for 25+ languages and customizable country/UI labels.
183

184
```typescript { .api }
185
type Labels = Partial<Record<LabelKey, string>>;
186
type LabelKey = Country | 'ZZ' | 'ext' | 'country' | 'phone';
187

188
// Locale imports
189
declare const en: Labels;
190
declare const de: Labels;
191
declare const fr: Labels;
192
// ... 25+ additional locales
193
```
194

195
[Internationalization](./internationalization.md)
196

197
### Customization and Styling
198

199
Extensive customization options including custom input components, country flag displays, and comprehensive CSS styling system.
200

201
```typescript { .api }
202
interface CustomizationProps {
203
  inputComponent?: React.ElementType;
204
  countrySelectComponent?: React.ElementType;
205
  flagComponent?: (props: FlagProps) => JSX.Element;
206
  flags?: Flags;
207
  containerComponent?: React.ElementType;
208
  // ... styling and layout options
209
}
210
```
211

212
[Customization and Styling](./customization.md)
213

214
## Types
215

216
```typescript { .api }
217
// Core value types
218
type Country = CountryCode; // Two-letter country code (e.g., "US", "DE")
219
type Value = E164Number;    // E.164 formatted phone number (e.g., "+12133734253")
220

221
// Component prop types  
222
type DefaultInputComponentProps = {
223
  [anyProperty: string]: any;
224
};
225

226
// Metadata and localization
227
type Metadata = MetadataJson;
228
type Labels = Partial<Record<LabelKey, string>>;
229
type Flags = Partial<Record<Country, EmbeddedFlag>>;
230

231
// Flag component types
232
interface FlagProps {
233
  country: Country;
234
  countryName: string;
235
  flagUrl?: string;
236
  flags?: Flags;
237
}
238

239
interface EmbeddedFlagProps {
240
  title: string;
241
}
242

243
type EmbeddedFlag = (props: EmbeddedFlagProps) => JSX.Element;
244
type Flag = (props: FlagProps) => JSX.Element;
245

246
// PhoneNumber class (from libphonenumber-js)
247
declare class PhoneNumber {
248
  country?: Country;
249
  countryCallingCode: string;
250
  nationalNumber: string;
251
  number: string;
252
  // ... additional properties and methods
253
}
254
```