0
# Input-Only Components
1

2
Streamlined phone number input components without country selection dropdowns. These components focus purely on phone number input with automatic formatting and validation, ideal when country context is predetermined or handled separately.
3

4
## Capabilities
5

6
### Main Input Component
7

8
Phone number input component without country selection dropdown.
9

10
```typescript { .api }
11
/**
12
 * Phone number input component without country selection
13
 * Provides formatting and validation for a specific country or international format
14
 */
15
interface Props<InputComponentProps> {
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
  /** Specific country for national formatting (two-letter country code) */
21
  country?: Country;
22
  /** Force international format input */
23
  international?: boolean;
24
  /** Include country calling code in input field when international=true */
25
  withCountryCallingCode?: boolean;
26
  /** Default country for ambiguous numbers */
27
  defaultCountry?: Country;
28
  /** Use national format for default country initial value */
29
  useNationalFormatForDefaultCountryValue?: boolean;
30
  /** Custom input component */
31
  inputComponent?: React.ElementType;
32
  /** Enable smart caret positioning */
33
  smartCaret?: boolean;
34
  /** Standard input properties */
35
  placeholder?: string;
36
  disabled?: boolean;
37
  readOnly?: boolean;
38
  autoComplete?: string;
39
  className?: string;
40
  style?: object;
41
  onFocus?(event: React.FocusEvent<HTMLElement>): void;
42
  onBlur?(event: React.FocusEvent<HTMLElement>): void;
43
}
44

45
declare const PhoneInput: React.ForwardRefExoticComponent<Props<DefaultInputComponentProps>>;
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
import React, { useState } from "react";
52
import PhoneInput from "react-phone-number-input/input";
53

54
// National format for specific country
55
function NationalFormatExample() {
56
  const [value, setValue] = useState();
57
  return (
58
    <PhoneInput
59
      country="US"
60
      value={value}
61
      onChange={setValue}
62
      placeholder="Enter US phone number"
63
    />
64
  );
65
}
66

67
// International format
68
function InternationalFormatExample() {
69
  const [value, setValue] = useState();
70
  return (
71
    <PhoneInput
72
      international
73
      value={value}
74
      onChange={setValue}
75
      placeholder="Enter international phone number"
76
    />
77
  );
78
}
79

80
// With country calling code visible
81
function WithCallingCodeExample() {
82
  const [value, setValue] = useState();
83
  return (
84
    <PhoneInput
85
      country="US"
86
      international
87
      withCountryCallingCode
88
      value={value}
89
      onChange={setValue}
90
      placeholder="+1"
91
    />
92
  );
93
}
94

95
// With default country fallback
96
function DefaultCountryExample() {
97
  const [value, setValue] = useState();
98
  return (
99
    <PhoneInput
100
      defaultCountry="US"
101
      value={value}
102
      onChange={setValue}
103
      placeholder="Enter phone number"
104
    />
105
  );
106
}
107
```
108

109
### Input Core Component
110

111
Core input component requiring manual metadata parameter.
112

113
```typescript { .api }
114
/**
115
 * Core input component requiring manual metadata
116
 * Use for custom metadata or smaller bundle sizes
117
 */
118
interface InputCoreProps<InputComponentProps> extends Props<InputComponentProps> {
119
  /** libphonenumber-js metadata object (required) */
120
  metadata: Metadata;
121
}
122

123
declare const PhoneInput: React.ForwardRefExoticComponent<InputCoreProps<DefaultInputComponentProps>>;
124
```
125

126
**Usage Example:**
127

128
```typescript
129
import PhoneInput from "react-phone-number-input/input-core";
130
import metadata from "libphonenumber-js/metadata.json";
131

132
function InputCoreExample() {
133
  const [value, setValue] = useState();
134
  return (
135
    <PhoneInput
136
      country="US"
137
      value={value}
138
      onChange={setValue}
139
      metadata={metadata}
140
    />
141
  );
142
}
143
```
144

145
### Input Bundle Variants
146

147
Different bundle size variants with the same API.
148

149
```typescript { .api }
150
// Minimal bundle size
151
import PhoneInput from "react-phone-number-input/input-min";
152

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

156
// Mobile-optimized
157
import PhoneInput from "react-phone-number-input/input-mobile";
158
```
159

160
### Format Behavior
161

162
Input components behave differently based on props configuration:
163

164
#### Country-Specific National Format
165
When `country` prop is provided without `international`:
166
- Input accepts only national format for that country
167
- Example: US numbers as "(213) 373-4253"
168
- Output is still E.164 format: "+12133734253"
169

170
#### International Format
171
When `international` prop is true:
172
- Input accepts international format
173
- Country calling code handling depends on other props
174

175
#### Default Country Mode  
176
When `defaultCountry` prop is provided:
177
- Input accepts both national and international formats
178
- National format numbers are parsed using the default country
179
- International format numbers are parsed as-is
180

181
### Input Component Integration
182

183
Input components support custom input component integration.
184

185
```typescript { .api }
186
/**
187
 * Custom input component interface
188
 * Must use React.forwardRef() to forward ref to underlying input
189
 */
190
interface CustomInputProps {
191
  value: string;
192
  onChange(event: React.ChangeEvent<HTMLInputElement>): void;
193
  onKeyDown?(event: React.KeyboardEvent<HTMLInputElement>): void;
194
  onPaste?(event: React.ClipboardEvent<HTMLInputElement>): void;
195
  // Any other standard input props
196
}
197

198
type InputComponent<InputComponentProps> = 
199
  | ((props: InputComponentProps) => JSX.Element)
200
  | React.ComponentClass<InputComponentProps>
201
  | React.ForwardRefExoticComponent<InputComponentProps>;
202
```
203

204
**Custom Input Example:**
205

206
```typescript
207
import React, { forwardRef } from "react";
208
import PhoneInput from "react-phone-number-input/input";
209

210
const CustomTextInput = forwardRef<HTMLInputElement, any>((props, ref) => (
211
  <input
212
    {...props}
213
    ref={ref}
214
    className="custom-input-style"
215
    style={{ border: '2px solid blue', borderRadius: '8px' }}
216
  />
217
));
218

219
function CustomInputExample() {
220
  const [value, setValue] = useState();
221
  return (
222
    <PhoneInput
223
      inputComponent={CustomTextInput}
224
      country="US"
225
      value={value}
226
      onChange={setValue}
227
    />
228
  );
229
}
230
```
231

232
### Smart Caret Positioning
233

234
Input components support intelligent caret positioning during editing.
235

236
```typescript { .api }
237
interface SmartCaretProps {
238
  /** Enable/disable smart caret positioning (default: true) */
239
  smartCaret?: boolean;
240
}
241
```
242

243
Smart caret behavior:
244
- Moves caret to next digit position when inserting in middle of formatted number
245
- Handles format changes that alter digit positions
246
- Can be disabled if it causes issues with specific input components
247
- Skips punctuation and spacing in formatted display
248

249
### Value Handling
250

251
Input components handle various value formats consistently.
252

253
```typescript { .api }
254
// Input value types
255
type InputValue = string | undefined;
256

257
// onChange signature  
258
onChange(value?: string): void;
259
```
260

261
Value handling rules:
262
- `undefined`, `null`, or empty string are treated as "empty"
263
- onChange always calls with `undefined` for empty values (not `null` or `""`)
264
- Input accepts E.164 format or external string values
265
- Output is always E.164 format or `undefined`
266
- Invalid numbers result in `undefined` onChange calls
267

268
**Value Handling Examples:**
269

270
```typescript
271
function ValueHandlingExample() {
272
  const [value, setValue] = useState<string | undefined>();
273
  
274
  const handleChange = (newValue: string | undefined) => {
275
    setValue(newValue);
276
    
277
    if (newValue === undefined) {
278
      console.log('Phone number cleared or invalid');
279
    } else {
280
      console.log('Valid phone number:', newValue); // E.164 format
281
    }
282
  };
283
  
284
  return (
285
    <PhoneInput
286
      country="US"
287
      value={value}
288
      onChange={handleChange}
289
      placeholder="(555) 123-4567"
290
    />
291
  );
292
}
293
```
294

295
### Error States
296

297
Input components handle various error conditions:
298

299
- Invalid input automatically formats or clears invalid characters
300
- Incomplete numbers do not trigger onChange until valid
301
- Overly long numbers are truncated based on country metadata  
302
- Numbers invalid for selected country result in `undefined` onChange calls