Skip to content

Commit 5c6cbef

Browse files
committed
PhoneInput: full ITU-T E.164 country list + basic validation
Expand the built-in country list from 50 to all 244 ITU-T E.164 entries. English names are derived at load from Intl.DisplayNames and flags from the ISO code's regional-indicator symbols, so neither is stored in the bundle; the original 50 keep their order, with the rest appended A-Z. Add preferredCountries (pinned above a divider, unioned into the menu) and accept bare ISO strings in countries. Add opt-in basic E.164 validation: validate marks a malformed non-empty number aria-invalid and onValidityChange(valid, e164) reports the normalized value. No new dependency; country table lives inside the component. Closes #32
1 parent 12c45d5 commit 5c6cbef

7 files changed

Lines changed: 763 additions & 125 deletions

File tree

‎content/docs/components/inputs/phone-input.mdx‎

Lines changed: 75 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Phone Input
3-
description: International phone number input with country selector, flag emojis, and dial code search. Supports 50 countries with built-in formatting and validation.
3+
description: International phone number input with country selector, flag emojis, and dial code search. Covers every E.164 country (~244 entries) with optional E.164 validation.
44
---
55

66
import { PreviewComponents } from "@/components/docs/preview-components";
@@ -121,6 +121,28 @@ the uncontrolled default. When `country` is controlled, the parent has the final
121121
say — honour `onCountryChange` if you want dial-code detection (below) to
122122
switch countries.
123123

124+
### Country list
125+
126+
`PhoneInput` ships with every ITU-T E.164 country (~244 entries), so any dial
127+
code can be selected. Each country's English name comes from
128+
[`Intl.DisplayNames`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames)
129+
and its flag is derived from the ISO code — neither is stored in the bundle.
130+
131+
Restrict or reorder the menu with `countries`, which accepts full `Country`
132+
objects or bare ISO codes:
133+
134+
```tsx
135+
<PhoneInput countries={["IN", "US", "GB"]} defaultCountry="IN" />
136+
```
137+
138+
Pin always-available markets to the top with `preferredCountries`. Preferred
139+
entries are placed above a divider, deduplicated, and **added** to the menu even
140+
when they are not in `countries`:
141+
142+
```tsx
143+
<PhoneInput countries={["US", "CA"]} preferredCountries={["IN", "GB"]} />
144+
```
145+
124146
### Dial-code detection
125147

126148
Type or paste a number that starts with `+` and the component switches the
@@ -145,31 +167,57 @@ the field — the prefix the `+` declares outranks a manually picked country:
145167
overrides the detected one, and nothing re-detects until the next time the
146168
value starts with `+`.
147169

170+
## Validation
171+
172+
Basic E.164 validation is built in, with no extra dependencies. The component
173+
normalizes the number (stripping spaces, dashes, dots, and parentheses), treats
174+
the remainder as digits-only, and enforces the E.164 maximum of 15 digits
175+
including the country code. Per-country length rules (`libphonenumber`) are
176+
deliberately out of scope.
177+
178+
- Pass `onValidityChange` to receive `(valid, e164)` whenever the digits change.
179+
`e164` is `"+"` plus every digit, the country code included — for example
180+
`"+15550001111"`. It does not fire on mount, nor for an edit that leaves the
181+
normalized number unchanged (formatting only).
182+
- Pass `validate` to also set `aria-invalid` on the input when a **non-empty**
183+
number is malformed. The field turns red through the same token styling as
184+
shadcn's `Input`; an empty field is never marked invalid, since "required" is
185+
the form's concern. Your own `aria-invalid` always wins.
186+
- A well-formed but incomplete number is valid — validation checks shape, not
187+
whether the number is dialable.
188+
189+
```tsx
190+
<PhoneInput validate onValidityChange={(valid, e164) => setPhone(valid ? e164 : "")} />
191+
```
192+
148193
## Props
149194

150-
| Prop | Type | Required | Description |
151-
| ------------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
152-
| `value` | `string` | No | Phone number — pass this to control the component |
153-
| `defaultValue` | `string` | No | Initial phone number when uncontrolled |
154-
| `onValueChange` | `(phone: string, country: Country) => void` | No | Callback when phone number or country changes |
155-
| `country` | `string` | No | Selected country code (ISO 3166-1 alpha-2) — pass this to control the country |
156-
| `onCountryChange` | `(country: Country) => void` | No | Callback when the selected country changes — from the menu or dial-code detection |
157-
| `defaultCountry` | `string` | No | Initial country code when uncontrolled (ISO 3166-1 alpha-2, e.g. `"US"`, `"GB"`, `"IN"`; default: `"US"`) |
158-
| `countries` | `Country[]` | No | Countries offered, in display order (default: `COUNTRIES`) |
159-
| `placeholder` | `string` | No | Placeholder text |
160-
| `disabled` | `boolean` | No | Disable the input |
161-
| `showFlags` | `boolean` | No | Show country flag next to dial code (default: `true`) |
162-
| `size` | `"sm" \| "default" \| "lg"` | No | Field height (default: `"default"`) |
163-
| `align` | `"start" \| "end"` | No | Edge of the field the menu lines up with (default: `"start"`) |
164-
| `side` | `"top" \| "bottom"` | No | Preferred menu side; flips when there is no room (default: `"bottom"`) |
165-
| `searchPlaceholder` | `string` | No | Placeholder for the country search (default: `"Search countries..."`) |
166-
| `emptyMessage` | `ReactNode` | No | Shown when the search matches nothing (default: `"No countries found."`) |
167-
| `labels` | `Partial<PhoneInputLabels>` | No | Override the built-in English UI text (see below) |
168-
| `displayLocale` | `string` | No | Locale for country names, e.g. `"fr"` (default: English names) |
169-
| `maxHeight` | `number \| string` | No | Max height of the scrolling country list (default: `"15rem"`) |
170-
| `label` | `string` | No | Accessible label for the input |
171-
| `className` | `string` | No | Classes for the root wrapper |
172-
| `classNames` | `PhoneInputClassNames` | No | Per-part classes: `root`, `field`, `trigger`, `input`, `content`, `search`, `list`, `item`, `empty` |
195+
| Prop | Type | Required | Description |
196+
| -------------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
197+
| `value` | `string` | No | Phone number — pass this to control the component |
198+
| `defaultValue` | `string` | No | Initial phone number when uncontrolled |
199+
| `onValueChange` | `(phone: string, country: Country) => void` | No | Callback when phone number or country changes |
200+
| `country` | `string` | No | Selected country code (ISO 3166-1 alpha-2) — pass this to control the country |
201+
| `onCountryChange` | `(country: Country) => void` | No | Callback when the selected country changes — from the menu or dial-code detection |
202+
| `validate` | `boolean` | No | Mark the input `aria-invalid` when a non-empty number is malformed (default: `false`) |
203+
| `onValidityChange` | `(valid: boolean, e164: string) => void` | No | Callback with basic E.164 validity and the normalized number, whenever the digits change |
204+
| `defaultCountry` | `string` | No | Initial country code when uncontrolled (ISO 3166-1 alpha-2, e.g. `"US"`, `"GB"`, `"IN"`; default: `"US"`) |
205+
| `countries` | `(Country \| string)[]` | No | Countries offered, in display order; entries are `Country` objects or ISO codes (default: `COUNTRIES`) |
206+
| `preferredCountries` | `(Country \| string)[]` | No | Countries pinned above a divider at the top; added even when not in `countries`, and deduplicated |
207+
| `placeholder` | `string` | No | Placeholder text |
208+
| `disabled` | `boolean` | No | Disable the input |
209+
| `showFlags` | `boolean` | No | Show country flag next to dial code (default: `true`) |
210+
| `size` | `"sm" \| "default" \| "lg"` | No | Field height (default: `"default"`) |
211+
| `align` | `"start" \| "end"` | No | Edge of the field the menu lines up with (default: `"start"`) |
212+
| `side` | `"top" \| "bottom"` | No | Preferred menu side; flips when there is no room (default: `"bottom"`) |
213+
| `searchPlaceholder` | `string` | No | Placeholder for the country search (default: `"Search countries..."`) |
214+
| `emptyMessage` | `ReactNode` | No | Shown when the search matches nothing (default: `"No countries found."`) |
215+
| `labels` | `Partial<PhoneInputLabels>` | No | Override the built-in English UI text (see below) |
216+
| `displayLocale` | `string` | No | Locale for country names, e.g. `"fr"` (default: English names) |
217+
| `maxHeight` | `number \| string` | No | Max height of the scrolling country list (default: `"15rem"`) |
218+
| `label` | `string` | No | Accessible label for the input |
219+
| `className` | `string` | No | Classes for the root wrapper |
220+
| `classNames` | `PhoneInputClassNames` | No | Per-part classes: `root`, `field`, `trigger`, `input`, `content`, `search`, `list`, `item`, `empty` |
173221

174222
Any other prop — `name`, `required`, `autoComplete`, `aria-invalid`, `data-*` — is
175223
spread onto the underlying `<input>`, and the ref is forwarded to it, so the
@@ -369,9 +417,11 @@ scrolls.
369417

370418
## Features
371419

372-
- **50 countries** — pre-loaded with dial codes, flags, and names
420+
- **Every E.164 country** — ~244 entries, with flags derived from the ISO code and English names from `Intl.DisplayNames`
373421
- **Dropdown search** — filter countries by name or dial code
374422
- **Flag emojis** — auto-detected from country code, with `showFlags` toggle
423+
- **Preferred countries** — pin markets above a divider with `preferredCountries`
424+
- **Basic E.164 validation** — digits-only, ≤ 15 digits, with `onValidityChange` and opt-in `aria-invalid` via `validate`
375425
- **Keyboard accessible** — arrow keys, Home / End, Enter, and Escape navigation
376426
- **ARIA labels** — `role="combobox"` search field with `aria-activedescendant`, plus `aria-expanded`, `aria-haspopup`, and `aria-selected`
377427
- **Themeable** — styled with shadcn/ui tokens (`border-input`, `bg-popover`, `ring-ring`), so it follows your theme and dark mode
Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,25 @@
11
"use client";
22

3+
import { useState } from "react";
34
import { PhoneInput } from "@/registry/components/phone-input";
45

56
export function PhoneInputDemo() {
7+
const [e164, setE164] = useState("");
68
return (
7-
<PhoneInput
8-
defaultCountry="US"
9-
placeholder="(555) 000-0000"
10-
onValueChange={(phone, country) => console.log("Phone:", country.dialCode, phone)}
11-
size="default" // sm, default, lg
12-
className="w-full max-w-xs"
13-
/>
9+
<div className="w-full max-w-xs space-y-2">
10+
<PhoneInput
11+
defaultCountry="US"
12+
placeholder="(555) 000-0000"
13+
preferredCountries={["IN", "GB"]} // pinned above the full list
14+
validate // marks a malformed number aria-invalid
15+
onValueChange={(phone, country) => console.log("Phone:", country.dialCode, phone)}
16+
onValidityChange={(valid, value) => setE164(valid ? value : "")}
17+
size="default" // sm, default, lg
18+
className="w-full"
19+
/>
20+
<p className="text-xs text-muted-foreground">
21+
{e164 ? `E.164: ${e164}` : "Type a phone number"}
22+
</p>
23+
</div>
1424
);
1525
}

0 commit comments

Comments
 (0)