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
```