Phone Input
A phone number field that formats as you type and knows its country.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
country | Signal<CountryCode | null> | CountryCode | null | null | The 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. |
value | Signal<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. |
valid | Signal<boolean> | — | Receives whether the number is complete and valid for its country. An empty field counts as valid. |
disabled | Readable<boolean> | boolean | false | Disables the field. |
readOnly | boolean | false | Makes the field read-only. |
name | string | — | Submits the E.164 number with a form under this name. |
| Data attribute | Value |
|---|---|
[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 attribute | Value |
|---|---|
[data-phone-input-field] | Present |