Accessible Base UI primitives with canonical libphonenumber output. Works with zero config, composes down to every part, and styles with plain className.
$ pnpm add phonefield @base-ui/react{}What it handles
Every card below is the real component. Poke at it.
Root mirrors its state as data attributes, so validation styling is one class away: data-invalid:border-destructive. Type an incomplete number, then tab away. The error message is <PhoneField.Error />.
International numbers pick their country and collapse to national format. Click a clipboard chip.
Digits past the longest possible number for the country are rejected as you type or paste.
lang localizes names, sorting, and search through Intl. No translation files.
Alemania · Japón · Estados Unidos · España
Native-feeling history over formatted values: ⌘Z undoes a typing run, a paste, or a country change as one step.
usePhoneField() gives custom parts the value, state, and setters, so any picker can drive the field. Here: shadcn's Select in place of the built-in combobox.
import { usePhoneField } from "phonefield";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
function CountrySelect() {
const { country, countries, setCountry } = usePhoneField();
return (
<Select value={country.iso2} onValueChange={setCountry}>
<SelectTrigger><SelectValue /></SelectTrigger>
<SelectContent>
{countries.map((c) => (
<SelectItem key={c.iso2} value={c.iso2}>{c.flag} {c.name}</SelectItem>
))}
</SelectContent>
</Select>
);
}Composition
Every part is a Base UI part: it takes className, render, and its state as data attributes. One API, any design.
Group is the shell: data-focused and data-invalid drive the ring, while Label and Error are wired for you. Copy it into your components folder.
1import { CheckIcon, ChevronDownIcon } from "lucide-react";2import { PhoneField } from "phonefield";3import type * as React from "react";4import { cn } from "@/lib/utils";56type PhoneInputProps = Omit<PhoneField.RootProps, "className"> & {7 className?: string;8 label?: React.ReactNode;9 description?: React.ReactNode;10 placeholder?: PhoneField.InputProps["placeholder"];11 inputProps?: Omit<PhoneField.InputProps, "placeholder" | "className">;12};1314export function PhoneInput({15 className,16 label,17 description,18 placeholder,19 inputProps,20 children,21 ...props22}: PhoneInputProps) {23 return (24 <PhoneField.Root25 {...props}26 className={cn("grid w-full gap-1.5", className)}27 >28 {label ? (29 <PhoneField.Label className="text-sm font-medium text-foreground">30 {label}31 </PhoneField.Label>32 ) : null}33 <PhoneField.Group34 className={cn(35 "flex h-10 w-full min-w-0 items-stretch overflow-hidden rounded-lg border border-input bg-background shadow-xs transition-[border-color,box-shadow] duration-150",36 "data-focused:border-ring data-focused:ring-3 data-focused:ring-ring/40",37 "data-invalid:border-destructive data-invalid:ring-destructive/20",38 "data-disabled:cursor-not-allowed data-disabled:opacity-50",39 )}40 >41 <PhoneField.Country>42 <PhoneField.CountryTrigger className="group/trigger flex shrink-0 cursor-default items-center gap-1.5 border-input border-r px-3 text-sm outline-none select-none transition-colors duration-150 hover:bg-accent/60 focus-visible:bg-accent data-popup-open:bg-accent">43 <PhoneField.CountryValue>44 {(country) => (45 <>46 <span aria-hidden className="text-base leading-none">47 {country.flag}48 </span>49 <span className="tabular-nums text-muted-foreground">50 {country.dialCode}51 </span>52 </>53 )}54 </PhoneField.CountryValue>55 <PhoneField.CountryIcon className="text-muted-foreground transition-transform duration-150 ease-out group-data-popup-open/trigger:rotate-180 motion-reduce:transition-none">56 <ChevronDownIcon className="size-3.5" />57 </PhoneField.CountryIcon>58 </PhoneField.CountryTrigger>59 <PhoneField.CountryPortal>60 <PhoneField.CountryPositioner61 className="isolate z-50"62 sideOffset={6}63 >64 <PhoneField.CountryPopup className="flex max-h-[min(22rem,var(--available-height))] w-72 max-w-(--available-width) origin-(--transform-origin) flex-col overflow-hidden rounded-xl bg-popover text-popover-foreground shadow-xl ring-1 ring-foreground/10 transition-[transform,opacity] duration-150 ease-out data-ending-style:[transform:scale(0.97)] data-ending-style:opacity-0 data-starting-style:[transform:scale(0.97)] data-starting-style:opacity-0 motion-reduce:transition-none">65 <div className="border-b p-1.5">66 <PhoneField.CountrySearch className="h-8 w-full rounded-md bg-muted/60 px-2.5 text-sm outline-none placeholder:text-muted-foreground focus-visible:ring-2 focus-visible:ring-ring/50" />67 </div>68 <PhoneField.CountryEmpty className="px-3 py-6 text-center text-sm text-muted-foreground empty:hidden" />69 <PhoneField.CountryList className="min-h-0 flex-1 scroll-py-1 overflow-y-auto overscroll-contain p-1 data-empty:p-0 [&_[data-preferred]]:mb-1 [&_[data-preferred]]:border-b [&_[data-preferred]]:pb-1">70 {(country) => (71 <PhoneField.CountryItem72 country={country}73 className="flex cursor-default items-center gap-2.5 rounded-md px-2.5 py-1.5 text-sm outline-none select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground"74 >75 <span aria-hidden className="text-base leading-none">76 {country.flag}77 </span>78 <span className="min-w-0 flex-1 truncate">79 {country.name}80 </span>81 <span className="tabular-nums text-muted-foreground">82 {country.dialCode}83 </span>84 <PhoneField.CountryItemIndicator className="text-foreground">85 <CheckIcon className="size-3.5" />86 </PhoneField.CountryItemIndicator>87 </PhoneField.CountryItem>88 )}89 </PhoneField.CountryList>90 </PhoneField.CountryPopup>91 </PhoneField.CountryPositioner>92 </PhoneField.CountryPortal>93 </PhoneField.Country>94 <PhoneField.Input95 aria-label={label ? undefined : "Phone number"}96 {...inputProps}97 placeholder={placeholder}98 className="h-full min-w-0 flex-1 bg-transparent px-3 text-base tabular-nums outline-none placeholder:text-muted-foreground/70 disabled:cursor-not-allowed md:text-sm"99 />100 </PhoneField.Group>101 {description ? (102 <PhoneField.Description className="text-xs text-muted-foreground">103 {description}104 </PhoneField.Description>105 ) : null}106 <PhoneField.Error className="text-xs text-destructive" />107 {children}108 </PhoneField.Root>109 );110}Every option maps to a Root prop. The output updates from onValueChange and usePhoneField.
Tab away from an incomplete number to see data-invalid.
Recipes
Reference
Installation, usage patterns, and API reference. Everything you need to integrate PhoneField into your design system.
Install the package, render the three primitives, and compose more only where you need it.
Install
Add the package and Base UI.
Compose
Render Root, Country, and Input.
Integrate
Read Value or submit through FormData.
Install with your preferred manager. Copy the command with one click.
pnpm add phonefieldPeer dependencies: @base-ui/react >=1.9 <2, react >=19 <20, and react-dom >=19 <20. Building the package requires Node.js 22.18 or newer.
Zero config. Country renders a complete, accessible picker with search; Input formats as you type. Root runs uncontrolled and emits a normalized PhoneField.Value.
1import { PhoneField } from "phonefield";23export function SignupPhone() {4 return (5 <PhoneField.Root defaultCountry="US">6 <PhoneField.Country />7 <PhoneField.Input aria-label="Phone number" />8 </PhoneField.Root>9 );10}Root is a plain wrapper. Label targets the input, Group is the visual shell for Country and Input, and Description and Error are linked with aria-describedby. Error renders only while the field is invalid.
1import { PhoneField } from "phonefield";23export function AccountPhone() {4 return (5 <PhoneField.Root name="phone" required>6 <PhoneField.Label>Phone</PhoneField.Label>7 <PhoneField.Group>8 <PhoneField.Country />9 <PhoneField.Input />10 </PhoneField.Group>11 <PhoneField.Description>Used for sign-in codes.</PhoneField.Description>12 <PhoneField.Error />13 </PhoneField.Root>14 );15}Use when your form or global state owns the value. The second onValueChange argument says why the value changed.
1import { PhoneField } from "phonefield";2import * as React from "react";34export function CheckoutPhone() {5 const [phone, setPhone] = React.useState<PhoneField.InputValue>({6 countryIso2: "US",7 nationalNumber: "",8 });910 return (11 <PhoneField.Root12 value={phone}13 onValueChange={(next, { reason }) => {14 setPhone(next);15 if (reason === "paste") console.log("Pasted", next.e164);16 }}17 >18 <PhoneField.Country />19 <PhoneField.Input aria-label="Phone number" />20 </PhoneField.Root>21 );22}defaultValue and defaultCountry are read once on mount. Controlled inputs may provide only PhoneField.InputValue; derived fields are rebuilt and onValueChange always emits the complete PhoneField.Value.Cmd/Ctrl+Z to undo and Cmd/Ctrl+Shift+Z or Ctrl+Y to redo. A typing run undoes as one step; paste, cut, drop, and country changes are independent steps. The last 100 steps are kept, and replacing a controlled value starts a new history.+ and PhoneField selects its country, then keeps only the national number in the input. If countries excludes that country, the text is preserved and emitted as invalid. Digits beyond the longest possible number for the country are blocked; pass limitMaxLength={false} to allow them. A number is invalid when its detected country differs from the selected one, including countries that share a calling code.Pass children to Country to customize any piece. Every part maps to one Base UI Combobox part, takes className, style, and render, and has sensible default content you can replace.
1import { PhoneField } from "phonefield";2import { getExampleNumber } from "phonefield/utils";34export function ComposedPhone() {5 return (6 <PhoneField.Root defaultCountry="US" className="phone">7 <PhoneField.Label className="phone-label">Phone</PhoneField.Label>8 <PhoneField.Group className="phone-group">9 <PhoneField.Country>10 <PhoneField.CountryTrigger className="phone-trigger">11 <PhoneField.CountryValue>12 {(country) => `${country.flag} ${country.iso2}`}13 </PhoneField.CountryValue>14 <PhoneField.CountryIcon className="phone-trigger-icon" />15 </PhoneField.CountryTrigger>16 <PhoneField.CountryPortal>17 <PhoneField.CountryPositioner sideOffset={8}>18 <PhoneField.CountryPopup className="phone-popup">19 <PhoneField.CountrySearch className="phone-search" />20 <PhoneField.CountryEmpty className="phone-empty" />21 <PhoneField.CountryList className="phone-list">22 {(country) => (23 <PhoneField.CountryItem24 country={country}25 className="phone-item"26 >27 {country.flag} {country.name}28 <PhoneField.CountryItemIndicator />29 </PhoneField.CountryItem>30 )}31 </PhoneField.CountryList>32 </PhoneField.CountryPopup>33 </PhoneField.CountryPositioner>34 </PhoneField.CountryPortal>35 </PhoneField.Country>36 <PhoneField.Input37 className="phone-input"38 placeholder={(country) => getExampleNumber(country.iso2)}39 />40 </PhoneField.Group>41 <PhoneField.Error className="phone-error" />42 </PhoneField.Root>43 );44}Read the value, field state, and countries from any component inside Root, and drive it with setCountry and setNumber. Useful for native selects, drawers, and status text.
1import { PhoneField, usePhoneField } from "phonefield";2import {3 Select,4 SelectContent,5 SelectItem,6 SelectTrigger,7 SelectValue,8} from "@/components/ui/select";910// Any part can read and drive Root. Here, shadcn's Select replaces Country.11function CountrySelect() {12 const { country, countries, setCountry, state } = usePhoneField();13 const items = countries.map((option) => ({14 value: option.iso2,15 label: `${option.flag} ${option.dialCode}`,16 }));1718 return (19 <Select20 items={items}21 value={country.iso2}22 disabled={state.disabled}23 onValueChange={(iso2) => {24 if (iso2) setCountry(iso2);25 }}26 >27 <SelectTrigger aria-label={`Country: ${country.name}`}>28 <SelectValue />29 </SelectTrigger>30 <SelectContent alignItemWithTrigger={false}>31 {countries.map((option) => (32 <SelectItem key={option.iso2} value={option.iso2}>33 {option.flag} {option.name} ({option.dialCode})34 </SelectItem>35 ))}36 </SelectContent>37 </Select>38 );39}4041export function CompactPhone() {42 return (43 <PhoneField.Root defaultCountry="US">44 <PhoneField.Group className="flex gap-2">45 <CountrySelect />46 <PhoneField.Input aria-label="Phone number" />47 </PhoneField.Group>48 </PhoneField.Root>49 );50}countries restricts the list to an ordered subset. preferredCountries pins countries to the top of the full list.
1import { PhoneField } from "phonefield";23// Only these countries, in this order.4export function NorthAmericaPhone() {5 return (6 <PhoneField.Root countries={["US", "CA", "MX"]}>7 <PhoneField.Country />8 <PhoneField.Input aria-label="Phone number" />9 </PhoneField.Root>10 );11}1213// Every country, with these pinned to the top.14export function PinnedPhone() {15 return (16 <PhoneField.Root preferredCountries={["US", "GB"]}>17 <PhoneField.Country />18 <PhoneField.Input aria-label="Phone number" />19 </PhoneField.Root>20 );21}lang localizes country names, sorting, search, and the trigger's accessible name. labels translates the search placeholder and empty text, with or without composed parts.
1import { PhoneField } from "phonefield";2import { getExampleNumber } from "phonefield/utils";34// lang localizes country names, sorting, search, and the trigger label.5// labels translates the picker's search placeholder and empty text.6export function ArgentinaPhone() {7 return (8 <PhoneField.Root lang="es-AR" defaultCountry="AR">9 <PhoneField.Label>Teléfono</PhoneField.Label>10 <PhoneField.Country11 labels={{ search: "Buscar país", empty: "Sin resultados" }}12 />13 <PhoneField.Input14 placeholder={(country) => getExampleNumber(country.iso2)}15 />16 <PhoneField.Error>17 {(state) =>18 state.filled ? "Ingresá un número válido." : "Ingresá un número."19 }20 </PhoneField.Error>21 </PhoneField.Root>22 );23}defaultCountry. Do not replace it after mount from a browser-only locale lookup: defaults are read once, and replacing them can overwrite a user's selection.Intl.DisplayNames, which can differ between Node and browsers for a few regions. The default picker server-renders only the selected country's name. Rendering every name on the server (a native select, an always-open list) can cause hydration warnings; render those lists on the client.Every part is unstyled. Style each one with className; Group is the field shell and carries field state as data attributes.
Recommended
Using Tailwind or class utilities?
Pass className to each part. Style the shell on Group with data-focused:, data-invalid:, and data-disabled:.
Alternative
Using CSS or CSS Modules?
Target the stable data-slot anatomy and the state attributes on Root and Group. Popup selectors must be global because the popup is rendered in a portal.
Group as one visual field, but keep Country and Input as separate accessible controls. Label, Group, Description, and Error all carry the field's state attributes. The popup is portaled out of Root: style its parts directly, or read usePhoneField().state in a wrapper when it must react to field state.State attributes on Group (and Root, Label, Description, Error) replace manual focus, touched, and validity tracking. className and style also accept a function of PhoneField.State.
1import { PhoneField } from "phonefield";23// Root is a plain wrapper. Group is the visual shell and mirrors field state4// as data attributes, so no React state is needed.5export function StatefulPhone() {6 return (7 <PhoneField.Root required className="grid gap-1.5">8 <PhoneField.Label>Phone</PhoneField.Label>9 <PhoneField.Group className="flex rounded-lg border data-focused:ring-2 data-invalid:border-red-500 data-disabled:opacity-50">10 <PhoneField.Country />11 <PhoneField.Input className="flex-1 px-3 outline-none" />12 </PhoneField.Group>13 <PhoneField.Error className="text-sm text-red-600" />14 </PhoneField.Root>15 );16}1718// className and style also accept a function of PhoneField.State.19export function StatusPhone() {20 return (21 <PhoneField.Root>22 <PhoneField.Group23 className={(state) => (state.valid ? "phone phone--valid" : "phone")}24 >25 <PhoneField.Country />26 <PhoneField.Input aria-label="Phone number" />27 </PhoneField.Group>28 </PhoneField.Root>29 );30}A reusable shadcn-style wrapper: Label, Description, and Error around a Group with one border and focus ring, and a styled popup composed from the parts.
1import { CheckIcon, ChevronDownIcon } from "lucide-react";2import { PhoneField } from "phonefield";3import type * as React from "react";4import { cn } from "@/lib/utils";56type PhoneInputProps = Omit<PhoneField.RootProps, "className"> & {7 className?: string;8 label?: React.ReactNode;9 description?: React.ReactNode;10 placeholder?: PhoneField.InputProps["placeholder"];11 inputProps?: Omit<PhoneField.InputProps, "placeholder" | "className">;12};1314export function PhoneInput({15 className,16 label,17 description,18 placeholder,19 inputProps,20 children,21 ...props22}: PhoneInputProps) {23 return (24 <PhoneField.Root25 {...props}26 className={cn("grid w-full gap-1.5", className)}27 >28 {label ? (29 <PhoneField.Label className="text-sm font-medium text-foreground">30 {label}31 </PhoneField.Label>32 ) : null}33 <PhoneField.Group34 className={cn(35 "flex h-10 w-full min-w-0 items-stretch overflow-hidden rounded-lg border border-input bg-background shadow-xs transition-[border-color,box-shadow] duration-150",36 "data-focused:border-ring data-focused:ring-3 data-focused:ring-ring/40",37 "data-invalid:border-destructive data-invalid:ring-destructive/20",38 "data-disabled:cursor-not-allowed data-disabled:opacity-50",39 )}40 >41 <PhoneField.Country>42 <PhoneField.CountryTrigger className="group/trigger flex shrink-0 cursor-default items-center gap-1.5 border-input border-r px-3 text-sm outline-none select-none transition-colors duration-150 hover:bg-accent/60 focus-visible:bg-accent data-popup-open:bg-accent">43 <PhoneField.CountryValue>44 {(country) => (45 <>46 <span aria-hidden className="text-base leading-none">47 {country.flag}48 </span>49 <span className="tabular-nums text-muted-foreground">50 {country.dialCode}51 </span>52 </>53 )}54 </PhoneField.CountryValue>55 <PhoneField.CountryIcon className="text-muted-foreground transition-transform duration-150 ease-out group-data-popup-open/trigger:rotate-180 motion-reduce:transition-none">56 <ChevronDownIcon className="size-3.5" />57 </PhoneField.CountryIcon>58 </PhoneField.CountryTrigger>59 <PhoneField.CountryPortal>60 <PhoneField.CountryPositioner61 className="isolate z-50"62 sideOffset={6}63 >64 <PhoneField.CountryPopup className="flex max-h-[min(22rem,var(--available-height))] w-72 max-w-(--available-width) origin-(--transform-origin) flex-col overflow-hidden rounded-xl bg-popover text-popover-foreground shadow-xl ring-1 ring-foreground/10 transition-[transform,opacity] duration-150 ease-out data-ending-style:[transform:scale(0.97)] data-ending-style:opacity-0 data-starting-style:[transform:scale(0.97)] data-starting-style:opacity-0 motion-reduce:transition-none">65 <div className="border-b p-1.5">66 <PhoneField.CountrySearch className="h-8 w-full rounded-md bg-muted/60 px-2.5 text-sm outline-none placeholder:text-muted-foreground focus-visible:ring-2 focus-visible:ring-ring/50" />67 </div>68 <PhoneField.CountryEmpty className="px-3 py-6 text-center text-sm text-muted-foreground empty:hidden" />69 <PhoneField.CountryList className="min-h-0 flex-1 scroll-py-1 overflow-y-auto overscroll-contain p-1 data-empty:p-0 [&_[data-preferred]]:mb-1 [&_[data-preferred]]:border-b [&_[data-preferred]]:pb-1">70 {(country) => (71 <PhoneField.CountryItem72 country={country}73 className="flex cursor-default items-center gap-2.5 rounded-md px-2.5 py-1.5 text-sm outline-none select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground"74 >75 <span aria-hidden className="text-base leading-none">76 {country.flag}77 </span>78 <span className="min-w-0 flex-1 truncate">79 {country.name}80 </span>81 <span className="tabular-nums text-muted-foreground">82 {country.dialCode}83 </span>84 <PhoneField.CountryItemIndicator className="text-foreground">85 <CheckIcon className="size-3.5" />86 </PhoneField.CountryItemIndicator>87 </PhoneField.CountryItem>88 )}89 </PhoneField.CountryList>90 </PhoneField.CountryPopup>91 </PhoneField.CountryPositioner>92 </PhoneField.CountryPortal>93 </PhoneField.Country>94 <PhoneField.Input95 aria-label={label ? undefined : "Phone number"}96 {...inputProps}97 placeholder={placeholder}98 className="h-full min-w-0 flex-1 bg-transparent px-3 text-base tabular-nums outline-none placeholder:text-muted-foreground/70 disabled:cursor-not-allowed md:text-sm"99 />100 </PhoneField.Group>101 {description ? (102 <PhoneField.Description className="text-xs text-muted-foreground">103 {description}104 </PhoneField.Description>105 ) : null}106 <PhoneField.Error className="text-xs text-destructive" />107 {children}108 </PhoneField.Root>109 );110}The same presentation without Tailwind. Group state attributes drive the shell; data slots target the controls, the error, and the portaled popup.
1/* Group is the visual shell and carries field state as data attributes. */2[data-slot="phone-field-group"] {3 display: flex;4 height: 2.5rem;5 border: 1px solid #e2e8f0;6 border-radius: 0.5rem;7 overflow: hidden;8 transition:9 border-color 150ms,10 box-shadow 150ms;11}1213[data-slot="phone-field-group"][data-focused] {14 border-color: #0ea5e9;15 box-shadow: 0 0 0 3px rgb(14 165 233 / 0.15);16}1718[data-slot="phone-field-group"][data-invalid] {19 border-color: #ef4444;20}2122[data-slot="phone-field-group"][data-disabled] {23 opacity: 0.5;24}2526[data-slot="phone-field-error"] {27 color: #dc2626;28 font-size: 0.875rem;29}3031[data-slot="phone-field-country-trigger"],32[data-slot="phone-field-input"] {33 border: 0;34 background: transparent;35 outline: none;36 padding-inline: 0.75rem;37}3839[data-slot="phone-field-country-trigger"] {40 display: flex;41 align-items: center;42 gap: 0.5rem;43 border-right: 1px solid #e2e8f0;44}4546[data-slot="phone-field-input"] {47 flex: 1;48 min-width: 0;49}5051/* The popup is portaled out of Root: keep these selectors global. */52[data-slot="phone-field-country-popup"] {53 width: 18rem;54 max-height: min(22rem, var(--available-height));55 display: flex;56 flex-direction: column;57 transform-origin: var(--transform-origin);58 border-radius: 0.75rem;59 background: white;60 box-shadow: 0 20px 40px rgb(15 23 42 / 0.14);61}6263[data-slot="phone-field-country-list"] {64 overflow-y: auto;65}6667[data-slot="phone-field-country-group"][data-preferred] {68 border-bottom: 1px solid #e2e8f0;69}7071[data-slot="phone-field-country-item"][data-highlighted] {72 background: #f1f5f9;73}7475[data-slot="phone-field-country-empty"]:empty {76 display: none;77}Base UI state attributes compose with these slots. For example, style an open trigger with [data-popup-open] and a highlighted country with [data-highlighted]. Field state attributes are listed in the Component API. With render, PhoneField's data-slot replaces the rendered component's own.
Choose the state model that matches your form and rebuild trusted values at the boundary.
fromFormData at the server boundary to rebuild E.164 and validity instead of accepting derived client values.Set name on Root to submit one entry with countryIso2 and nationalNumber. Submitting the form marks the field touched, so errors show without a prior blur; resetting it restores an uncontrolled field's initial value. Use form for a form outside Root. A disabled field is not submitted.
1import { PhoneField } from "phonefield";2import { fromFormData } from "phonefield/utils";3import { Button } from "@/components/ui/button";45export function ContactForm() {6 return (7 <form8 onSubmit={(event) => {9 event.preventDefault();10 const phone = fromFormData(new FormData(event.currentTarget), "phone");11 console.log(phone?.e164, phone?.isValid);12 }}13 >14 {/* Submitting shows the error without a prior blur; reset restores the value. */}15 <PhoneField.Root name="phone" defaultCountry="US" required>16 <PhoneField.Label>Phone</PhoneField.Label>17 <PhoneField.Country />18 <PhoneField.Input />19 <PhoneField.Error />20 </PhoneField.Root>21 <Button type="reset" variant="outline">22 Reset23 </Button>24 <Button type="submit">Continue</Button>25 </form>26 );27}2829// The same helper runs on the server. Never trust client-derived fields.30export function parseSubmittedPhone(formData: FormData) {31 const phone = fromFormData(formData, "phone");32 return phone?.isValid ? phone.e164 : null;33}After blur or submit, the field is invalid when the number is incomplete or invalid, or required and empty. Input gets aria-invalid, Group gets data-invalid, and Error appears. invalid={!!serverError} adds an external error; automatic validation still applies when it is false.
1import { PhoneField } from "phonefield";23export function ValidatedPhone({ serverError }: { serverError?: string }) {4 return (5 <PhoneField.Root6 name="phone"7 required8 invalid={!!serverError}9 className="space-y-1.5"10 >11 <PhoneField.Label>Phone</PhoneField.Label>12 <PhoneField.Group className="flex rounded-lg border data-focused:ring-2 data-invalid:border-red-500">13 <PhoneField.Country />14 <PhoneField.Input />15 </PhoneField.Group>16 <PhoneField.Description>We'll text you a code.</PhoneField.Description>17 <PhoneField.Error className="text-sm text-red-600">18 {(state) =>19 serverError ??20 (state.filled ? "Enter a valid number." : "Phone is required.")21 }22 </PhoneField.Error>23 </PhoneField.Root>24 );25}required also sets the native attribute on Input, so the browser blocks an empty submit. The trigger is named after the selected country unless you give it aria-label, aria-labelledby, or an id for your own label. Do not wrap both controls in one Base UI Field: PhoneField provides its own Label, Description, and Error.Props, state attributes, and parts for Root, the field parts, Input, and Country, plus the usePhoneField hook.
Owns the value, field state, and form serialization. Renders a plain div wrapper; every other part must be inside it.
Root and Group mirror PhoneField.State as data attributes, so you can style the field without tracking state. The same object is passed to className and style functions and returned by usePhoneField().state. Boolean attributes are present only when true.
Label, Group, Description, and Error take className and style (static or a function of PhoneField.State), render, and the props of their element. They carry the same state attributes as Root. With render, PhoneField's data-slot replaces the rendered component's own.
A Base UI Input bound to Root. Formatting, paste, undo, and length limits are handled for you.
A Base UI Combobox.Root whose selection is managed by Root. Without children it renders the full default anatomy, unstyled.
Each part accepts className and style (static or a function of the part's Base UI state), render, and the props of the Base UI part it wraps. Parts below Portal render outside Root, so style them directly rather than through Root selectors.
Reads and drives the nearest Root from your own parts: a native select, a drawer, or a status message. Must be called inside PhoneField.Root.
Parse, validate, format, and serialize the same way on the client and server.
parse() returns libphonenumber's PhoneNumber. String parsing is strict: pass { defaultCountry } for national numbers or { extract: true } for arbitrary text. getExampleNumber() returns a placeholder-ready example.
1import type { PhoneField } from "phonefield";2import {3 buildValue,4 countries,5 fromFormData,6 getCountries,7 getExampleNumber,8 isValid,9 parse,10 toFormValue,11} from "phonefield/utils";1213export function inspectPhone(value: PhoneField.Value, formData: FormData) {14 const unitedStates = getCountries("en").get("US");1516 return {17 built: unitedStates ? buildValue(unitedStates, "4155552671", true) : null,18 defaultCountry: countries.get("US"),19 example: getExampleNumber("GB", "international"), // "+44 7400 123456"20 extracted: parse("Call +1 415 555 2671", { extract: true }),21 fromForm: fromFormData(formData, "phone"),22 isValid: isValid(value),23 national: parse("(415) 555-2671", { defaultCountry: "US" }),24 parsed: parse(value),25 serialized: toFormValue(value),26 };27}Named exports that run on the client and the server. Import only what you use.
The value model and submitted payload are unchanged. Country configuration props became composable parts, and field state, labels, errors, and form submit/reset handling are now built in.
Removed Country props fail the typecheck, so most steps are found for you. Two steps change behavior without a type error and are flagged below. @base-ui/react must be 1.9 or newer; React 18 remains unsupported. No phone data migration is required.
pnpm add phonefield@^2 @base-ui/react@^1.9Country no longer takes classNames. Compose the parts you want to style and pass className to each one. Zero-config <PhoneField.Country /> still renders the full picker.
1<PhoneField.Country2 classNames={{3 trigger: "trigger",4 popup: "popup",5 item: "item",6 }}7/>1<PhoneField.Country>2 <PhoneField.CountryTrigger className="trigger" />3 <PhoneField.CountryPortal>4 <PhoneField.CountryPositioner>5 <PhoneField.CountryPopup className="popup">6 <PhoneField.CountrySearch />7 <PhoneField.CountryEmpty />8 <PhoneField.CountryList>9 {(country) => (10 <PhoneField.CountryItem country={country} className="item" />11 )}12 </PhoneField.CountryList>13 </PhoneField.CountryPopup>14 </PhoneField.CountryPositioner>15 </PhoneField.CountryPortal>16</PhoneField.Country>Every Base UI Positioner prop is available. Defaults are unchanged: side="bottom", align="start", sideOffset={4}.
1<PhoneField.Country2 positioning={{ side: "top", sideOffset: 8 }}3/>1<PhoneField.CountryPositioner side="top" sideOffset={8}>2 <PhoneField.CountryPopup>…</PhoneField.CountryPopup>3</PhoneField.CountryPositioner>CountryValue and CountryList take a function of the country. List keys are handled for you. icon becomes the children of CountryIcon.
1<PhoneField.Country2 icon={<ChevronDown />}3 renderCountryValue={(c) => c.dialCode}4 renderCountryItem={(c) => c.name}5/>1<PhoneField.CountryTrigger>2 <PhoneField.CountryValue>{(c) => c.dialCode}</PhoneField.CountryValue>3 <PhoneField.CountryIcon><ChevronDown /></PhoneField.CountryIcon>4</PhoneField.CountryTrigger>5…6<PhoneField.CountryList>7 {(c) => <PhoneField.CountryItem country={c}>{c.name}</PhoneField.CountryItem>}8</PhoneField.CountryList>slotProps.root becomes props on Country (open, onOpenChange, modal…). Every other slot becomes props on its part.
1<PhoneField.Country2 slotProps={{3 root: { modal: true, onOpenChange },4 trigger: { "aria-label": "Country" },5 }}6/>1<PhoneField.Country modal onOpenChange={onOpenChange}>2 <PhoneField.CountryTrigger aria-label="Country" />3 …4</PhoneField.Country>inputPlaceholder and noResultsText become Country labels, which also apply to composed parts. Props on CountrySearch and CountryEmpty still win. placeholder is removed: a country is always selected.
1<PhoneField.Country2 inputPlaceholder="Buscar país"3 noResultsText="Sin resultados"4/>1<PhoneField.Country2 labels={{ search: "Buscar país", empty: "Sin resultados" }}3/>Root tracks touched, focus, and validity; submitting the form reveals errors and reset restores the value. Group is the styled shell with data-invalid, Error renders only while invalid, and both Description and Error are linked with aria-describedby.
1const [touched, setTouched] = useState(false);2const invalid = touched && !phone.isValid;34<label htmlFor="phone">Phone</label>5<PhoneField.Root className={invalid ? "error" : ""}>6 <PhoneField.Country />7 <PhoneField.Input8 id="phone"9 aria-invalid={invalid || undefined}10 aria-describedby="phone-error"11 onBlur={() => setTouched(true)}12 />13</PhoneField.Root>14{invalid && <p id="phone-error">Invalid number</p>}1<PhoneField.Root required invalid={!!serverError}>2 <PhoneField.Label>Phone</PhoneField.Label>3 <PhoneField.Group className="data-invalid:border-red-500">4 <PhoneField.Country />5 <PhoneField.Input />6 </PhoneField.Group>7 <PhoneField.Error>{serverError}</PhoneField.Error>8</PhoneField.Root>A second argument reports why the value changed. Existing one-argument callbacks keep working.
1onValueChange={(value) => save(value)}1onValueChange={(value, { reason }) => {2 // "input" | "paste" | "country" | "undo" | "redo"3 if (reason !== "country") save(value);4}}Behavior change
limitMaxLength now defaults to true: typing or pasting more digits than any number in the country can have is ignored. Opt out to keep v1 behavior.
1<PhoneField.Root>1<PhoneField.Root limitMaxLength={false}>Behavior change
The default trigger content is now "🇺🇸 +1" instead of "🇺🇸 United States (+1)". Its accessible name stays "United States (+1)", so role queries keep working; text queries do not.
1screen.getByText("🇺🇸 United States (+1)");1screen.getByRole("combobox", { name: "United States (+1)" });2// or restore the old content:3<PhoneField.CountryValue>4 {(c) => `${c.flag} ${c.name} (${c.dialCode})`}5</PhoneField.CountryValue>