Phone field

When to use #

Use it for

Sign-up and contact forms that need international numbers.
You want formatting as people type and a valid flag.

Skip it when

You only collect numbers for one country; a plain input with a pattern is lighter.

Installation #

terminal

pnpm dlx shadcn@latest add https://caliperui.site/r/phone-field.json

Adds its 3 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above. It is built from PhoneField and parsePhone.

example.tsx

import { useState } from "react"
import { PhoneField } from "@/components/ui/phone-field"

export function ContactPhone() {
  const [phone, setPhone] = useState("");
  return (
    <div className="w-full max-w-xs">
      <PhoneField label="Phone" value={phone} onValueChange={setPhone} defaultCountry="US" />
    </div>
  );
}

API reference #

PhoneField

component

PropTypeDefault

labelstring"Phone number"

valuestring—

defaultValuestring""

countrystring—

defaultCountrystring"US"

countriesreadonly string[]—

preferredCountriesreadonly string[]["US", "GB", "IN"]

descriptionstring—

disabledboolean—

requiredboolean—

namestring—

idstring—

onValueChange((value: string, details: PhoneDetails) => void)—

onCountryChange((iso: string) => void)—

classNamestring—

parsePhone

component

No props of its own; it accepts the native props of its root element.

phoneCountries

helper

A helper exported alongside the component, not a component.

It exposes listbox and option semantics, with aria-label, aria-expanded, aria-controls, aria-hidden, aria-invalid and aria-describedby kept in step with state.

KeyBehaviour

↓Moves to the next item or value.

↑Moves to the previous item or value.

EnterActivates the focused control.

EscapeCloses or cancels, then returns focus to where it came from.

Motion #

Transitions use the shared duration and easing tokens. Under prefers-reduced-motion those tokens collapse to instant and travel distances go to zero, so state changes still happen without movement.