Phone Input React component
A phone number input with a searchable country menu: flags and calling codes, as-you-type formatting per country, paste detection for +codes, an E.164 value and a length check.
About the Phone Input component
Phone Input is a phone number field with a country picker in front of it. Picking a country shows its flag and calling code, the number formats itself with that country's spacing as you type, and a leading trunk 0 typed out of habit is dropped. Pasting a full international number starting with + switches to the matching country, and the field checks the length once you leave it.
The value is always in E.164 format, such as "+14155550123", through value or defaultValue, and onValueChange also passes the country, the national digits and isValid. country or defaultCountry (US by default) set the country, countries limits the list and preferredCountries pins some to the top. label, placeholder and helperText set the texts, errorText forces an error, invalidText sets the length message, and name adds a hidden input for plain form posts. The country list is exported as PHONE_COUNTRIES.
When to use it
Use Phone Input in sign-up, checkout, booking and contact forms. The value is always E.164 (for example "+905321234567"), the format SMS, WhatsApp and calling APIs expect, so you can store and send it without reformatting.
The built-in check only looks at the number's length for the chosen country. It catches typos and missing digits while typing; if you need to know that a number really exists or is a mobile line, verify it on your server with a library such as libphonenumber or with an SMS code.
Installation
Add the Phone Input component to your project with the shadcn CLI. It lands in components/phone-input.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/phone-inputOr copy the source by hand and install its dependencies:
npm install motion clsx tailwind-mergeProps
<PhoneInput /> accepts 19 props, all optional.
| Prop | Type | Default |
|---|---|---|
| value E.164 number, e.g. "+14155550123", or "" when empty. | string | — |
| defaultValue | string | "" |
| onValueChange | (value: string, meta: PhoneValueMeta) => void | — |
| country Selected country (ISO code), controlled. | string | — |
| defaultCountry | string | "US" |
| onCountryChange | (country: string) => void | — |
| countries Limit the menu to these ISO codes. | string[] | — |
| preferredCountries Pinned to the top of the menu, in this order. | string[] | [] |
| label | string | — |
| placeholder | string | — |
| helperText | string | — |
| errorText Forces an error state with this message. | string | — |
- value
E.164 number, e.g. "+14155550123", or "" when empty.
string - defaultValuestringDefault: ""
- onValueChange(value: string, meta: PhoneValueMeta) => void
- country
Selected country (ISO code), controlled.
string - defaultCountrystringDefault: "US"
- onCountryChange(country: string) => void
- countries
Limit the menu to these ISO codes.
string[] - preferredCountries
Pinned to the top of the menu, in this order.
string[]Default: [] - labelstring
- placeholderstring
- helperTextstring
- errorText
Forces an error state with this message.
string
Show all 19 propsShow fewer
| invalidText Shown after the field loses focus with an incomplete number; set to "" to turn the check off. | string | "Enter a valid phone number" |
| name Name for a hidden input carrying the E.164 value, for plain form posts. | string | — |
| size | "sm" | "md" | "lg" | "md" |
| theme | "dark" | "light" | "dark" |
| width | number | string | 320 |
| disabled | boolean | false |
| className | string | — |
- invalidText
Shown after the field loses focus with an incomplete number; set to "" to turn the check off.
stringDefault: "Enter a valid phone number" - name
Name for a hidden input carrying the E.164 value, for plain form posts.
string - size"sm" | "md" | "lg"Default: "md"
- theme"dark" | "light"Default: "dark"
- widthnumber | stringDefault: 320
- disabledbooleanDefault: false
- classNamestring
npm dependencies
Installed for you by the shadcn CLI.
Phone Input FAQ
- What format does it return?
- E.164: a plus, the calling code and the national number with no spaces, such as "+14155550123". onValueChange also gives the country code, the national digits and isValid.
- Can people paste an international number?
- Yes. A number that starts with + switches the country by its calling code, so pasting "+44 7911 123456" selects the United Kingdom.
- Can I limit or reorder the countries?
- Yes. countries limits the list to the ISO codes you pass, and preferredCountries pins some of them to the top of the menu.
- Why do I see letters instead of flags?
- The flags are emoji, and Windows does not draw country flag emoji, so it shows the two-letter code instead. The country name and calling code are still there, so the picker works the same.