implement
Phone Input

Phone Input

A phone number field that formats as you type and knows its country.

Enter a phone number.
import { Div, signal, Span } from "@implementjs/core";
import { PhoneInput, type CountryCode } from "@/lib/components/ui/phone-input";

export default function PhoneInputDemo() {
	const value = signal("");
	const country = signal<CountryCode | null>("US");

	return Div(
		{ class: "flex w-full max-w-sm flex-col gap-2" },
		PhoneInput({ value, country, placeholder: "Enter a phone number" }),
		Span(
			{ class: "text-sm text-muted-foreground" },
			value.bind((v) => (v === "" ? "Enter a phone number." : `E.164: ${v}`)),
		),
	);
}

A phone input formats a number as it is typed and keeps two things in sync: the country and the number in E.164 form (+15551234567), the one shape a server can store and compare. Parsing and formatting come from libphonenumber-js, which ships with the primitives.

The primitive owns the field only. The country picker is yours to build — see Building a country picker — and the styled version brings one.

import { PhoneInput, PhoneInputField } from "@implementjs/primitives";

PhoneInput({ country: "US", name: "phone" }, PhoneInputField({ placeholder: "(555) 123-4567" }));

Each part accepts optional props and children — pass a props object when you need attributes, or pass children directly. See createComponent. Extra props are forwarded onto the underlying Div or Input.

Country and value

Both take a string to seed them or a signal to control and observe them:

const country = signal<CountryCode | null>("US");
const value = signal("");

PhoneInput({ country, value, onValueChange: (e164) => save(e164) }, PhoneInputField());

With a country set, the field shows the number in national form — (213) 373-4253 — and value holds +12133734253. Write to value from outside and the field redraws to match.

Detecting the country

Type a number starting with + and the country is read from it: +44 7400 123456 sets country to "GB". With no country selected and no leading +, there is no way to know what the digits mean, so value stays empty.

Validity

valid receives true when the number is complete and valid for its country, and false while it is not. An empty field counts as valid, so pair it with required or your own check when a number is mandatory. The root also sets data-valid="false" while it is not.

Forms

Pass name to the root and the E.164 number submits with its form in a hidden input. The visible field is type="tel" with autocomplete="tel".

Building a country picker

getPhoneCountries(locale) lists every country as { code, name, dialCode }, sorted by name. PhoneInputContext.Use hands you the state of the nearest root: set country with state.setCountry(code), which keeps the digits already typed and moves them to the new country's calling code.

import { getPhoneCountries, PhoneInputContext } from "@implementjs/primitives";

PhoneInputContext.Use((state) =>
	Select(
		{ onChange: (e) => state.setCountry(e.currentTarget.value) },
		...getPhoneCountries().map((c) => Option({ value: c.code }, c.name)),
	),
);

state.country, state.value, state.valid, and state.disabled are readable, and state.focus() returns focus to the field — useful after a picker closes.

API Reference

PhoneInput

The root. Owns the country and the number, and provides them to the field and to any country picker you write. Renders a Div; extra props are forwarded onto it.

PropTypeDefaultDescription
countrySignal<CountryCode | null> | CountryCode | nullnullThe selected country, as an ISO 3166-1 alpha-2 code. Pass a signal to control it from outside. Typing a number that starts with + sets it.
onCountryChange(country: CountryCode | null) => void—Runs whenever the country changes.
valueSignal<string> | string""The number in E.164 form, like "+15551234567". Pass a signal to control it from outside.
onValueChange(value: string) => void—Runs whenever the number changes.
validSignal<boolean>—Receives whether the number is complete and valid for its country. An empty field counts as valid.
disabledReadable<boolean> | booleanfalseDisables the field.
readOnlybooleanfalseMakes the field read-only.
namestring—Submits the E.164 number with a form under this name.
Data attributeValue
[data-phone-input-root]Present
[data-disabled]Present when disabled
[data-valid]"false" when the number is not valid

PhoneInputField

The text field. Formats as you type and sets the root's number and country. Renders type="tel". Renders a Input; extra props are forwarded onto it.

Data attributeValue
[data-phone-input-field]Present
Country
Afghanistan+93
Åland Islands+358
Albania+355
Algeria+213
American Samoa+1
Andorra+376
Angola+244
Anguilla+1
Antigua & Barbuda+1
Argentina+54
Armenia+374
Aruba+297
Ascension Island+247
Australia+61
Austria+43
Azerbaijan+994
Bahamas+1
Bahrain+973
Bangladesh+880
Barbados+1
Belarus+375
Belgium+32
Belize+501
Benin+229
Bermuda+1
Bhutan+975
Bolivia+591
Bosnia & Herzegovina+387
Botswana+267
Brazil+55
British Indian Ocean Territory+246
British Virgin Islands+1
Brunei+673
Bulgaria+359
Burkina Faso+226
Burundi+257
Cambodia+855
Cameroon+237
Canada+1
Cape Verde+238
Caribbean Netherlands+599
Cayman Islands+1
Central African Republic+236
Chad+235
Chile+56
China+86
Christmas Island+61
Cocos (Keeling) Islands+61
Colombia+57
Comoros+269
Congo - Brazzaville+242
Congo - Kinshasa+243
Cook Islands+682
Costa Rica+506
Côte d’Ivoire+225
Croatia+385
Cuba+53
Curaçao+599
Cyprus+357
Czechia+420
Denmark+45
Djibouti+253
Dominica+1
Dominican Republic+1
Ecuador+593
Egypt+20
El Salvador+503
Equatorial Guinea+240
Eritrea+291
Estonia+372
Eswatini+268
Ethiopia+251
Falkland Islands+500
Faroe Islands+298
Fiji+679
Finland+358
France+33
French Guiana+594
French Polynesia+689
Gabon+241
Gambia+220
Georgia+995
Germany+49
Ghana+233
Gibraltar+350
Greece+30
Greenland+299
Grenada+1
Guadeloupe+590
Guam+1
Guatemala+502
Guernsey+44
Guinea+224
Guinea-Bissau+245
Guyana+592
Haiti+509
Honduras+504
Hong Kong SAR China+852
Hungary+36
Iceland+354
India+91
Indonesia+62
Iran+98
Iraq+964
Ireland+353
Isle of Man+44
Israel+972
Italy+39
Jamaica+1
Japan+81
Jersey+44
Jordan+962
Kazakhstan+7
Kenya+254
Kiribati+686
Kosovo+383
Kuwait+965
Kyrgyzstan+996
Laos+856
Latvia+371
Lebanon+961
Lesotho+266
Liberia+231
Libya+218
Liechtenstein+423
Lithuania+370
Luxembourg+352
Macao SAR China+853
Madagascar+261
Malawi+265
Malaysia+60
Maldives+960
Mali+223
Malta+356
Marshall Islands+692
Martinique+596
Mauritania+222
Mauritius+230
Mayotte+262
Mexico+52
Micronesia+691
Moldova+373
Monaco+377
Mongolia+976
Montenegro+382
Montserrat+1
Morocco+212
Mozambique+258
Myanmar (Burma)+95
Namibia+264
Nauru+674
Nepal+977
Netherlands+31
New Caledonia+687
New Zealand+64
Nicaragua+505
Niger+227
Nigeria+234
Niue+683
Norfolk Island+672
North Korea+850
North Macedonia+389
Northern Mariana Islands+1
Norway+47
Oman+968
Pakistan+92
Palau+680
Palestinian Territories+970
Panama+507
Papua New Guinea+675
Paraguay+595
Peru+51
Philippines+63
Poland+48
Portugal+351
Puerto Rico+1
Qatar+974
Réunion+262
Romania+40
Russia+7
Rwanda+250
Samoa+685
San Marino+378
São Tomé & Príncipe+239
Saudi Arabia+966
Senegal+221
Serbia+381
Seychelles+248
Sierra Leone+232
Singapore+65
Sint Maarten+1
Slovakia+421
Slovenia+386
Solomon Islands+677
Somalia+252
South Africa+27
South Korea+82
South Sudan+211
Spain+34
Sri Lanka+94
St. Barthélemy+590
St. Helena+290
St. Kitts & Nevis+1
St. Lucia+1
St. Martin+590
St. Pierre & Miquelon+508
St. Vincent & Grenadines+1
Sudan+249
Suriname+597
Svalbard & Jan Mayen+47
Sweden+46
Switzerland+41
Syria+963
Taiwan+886
Tajikistan+992
Tanzania+255
Thailand+66
Timor-Leste+670
Togo+228
Tokelau+690
Tonga+676
Trinidad & Tobago+1
Tristan da Cunha+290
Tunisia+216
Türkiye+90
Turkmenistan+993
Turks & Caicos Islands+1
Tuvalu+688
U.S. Virgin Islands+1
Uganda+256
Ukraine+380
United Arab Emirates+971
United Kingdom+44
United States+1
Uruguay+598
Uzbekistan+998
Vanuatu+678
Vatican City+39
Venezuela+58
Vietnam+84
Wallis & Futuna+681
Western Sahara+212
Yemen+967
Zambia+260
Zimbabwe+263