Components / PhoneInput

PhoneInput

A phone field with a searchable country selector and live per-country formatting. Pasting a number that starts with + switches the country and says so, with an undo. The country chip is an ISO code rather than a flag emoji, because Windows ships no glyphs for regional-indicator pairs and a flag degrades to two bare letters there.

$ npx shadcn@latest add https://input-cn.vercel.app/r/phone-input.json

Build with an agent

Hand this to Claude Code

1,656 chars

Most people reach this component through an agent rather than by reading the page. Pick how you want it wired and take a prompt that already carries the canonical value, the real prop names and the mistakes worth avoiding.

Wiring

Extras

Open in Claude Code

Nothing runs on its own. The link opens the tool with the prompt typed into the box; you read it and press Enter. If the button does nothing, Claude Code is not installed on this machine — use Copy prompt instead.

Live demo

Phone number

Paste +44 20 7123 4567 — the country switches with it.

value = "" · E.164

Constraints

Validation rules, declared as props. Each one produces its own message and its own data-rule value, so a test can assert the rule rather than the sentence.

PROPTYPEDESCRIPTION

countries?readonly string[]Restrict the selector and reject numbers outside the list.

mobileOnly?booleanReject numbers that look like landlines.

defaultCountry?stringCountry selected before the user picks one. Defaults to "US".

Props

PROPTYPEDESCRIPTION

label?ReactNodeVisible label. Supply this or `aria-label` — a field with neither has no accessible name.

hint?ReactNodeHelper text under the field. Replaced by the error message while one is showing.

renderCountry?(api: { country: Country | undefined available: readonly Country[] setCountry: (iso: string) => void disabled: boolean | undefined }) => ReactNodeOverride the country trigger and popover.

Shared props

Implemented identically by all eleven components. These tables are generated from the source interfaces at build time, so a renamed prop changes this page rather than quietly making it wrong.

PROPTYPEDESCRIPTION

value?TCanonical value. Controlled mode.

defaultValue?TCanonical value. Uncontrolled mode. Mutually exclusive with `value`.

onChange?(value: T) => voidEmits the canonical value — never a DOM event.

onBlur?() => voidFires when focus leaves the whole component, not between its parts.

name?stringApplied to the hidden canonical input so FormData carries the real value.

disabled?boolean—

readOnly?boolean—

required?boolean | string—

validate?(value: T) => true | stringCustom synchronous rule. Return true, or the message to display.

messages?MessageMapOverride built-in messages by rule name.

showError?ShowErrorDefault `"touched"`.

onValidityChange?(state: ValidityState) => voidReports validity upward regardless of mode.

mode?FieldModeForce a mode instead of auto-detecting. Escape hatch only.

variant?FieldVariantSurface treatment. Default `"outline"`.

size?FieldSizeDensity. Default `"default"` (32px).

id?string—

className?string—

placeholder?string—

autoFocus?boolean—

aria-label?string—

aria-labelledby?string—

aria-describedby?string—

aria-invalid?boolean | "true" | "false"—

With react-hook-form

import { useForm, Controller } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import { phoneSchema } from "@inputcn/phone/schema"
import { PhoneInput } from "@/components/ui/phone-input"
import { z } from "zod"

// The companion schema validates the CANONICAL value, so the resolver and the
// field can never disagree about what "valid" means.
const schema = z.object({ phone: phoneSchema() })

export function Example() {
  const { control } = useForm({ resolver: zodResolver(schema) })

  return (
    <Controller
      name="phone"
      control={control}
      render={({ field, fieldState }) => (
        <PhoneInput
          label="Phone number"
          {...field}
          aria-invalid={fieldState.invalid}
        />
      )}
    />
  )
}

With a Server Action

import { PhoneInput } from "@/components/ui/phone-input"

export default function Page() {
  return (
    <form action={save}>
      <PhoneInput name="phone" label="Phone number" />
      <button>Save</button>
    </form>
  )
}

async function save(data: FormData) {
  "use server"
  // The hidden canonical input carries the real value, not the display text.
  const phone = data.get("phone") // "+442071234567"
}

Keyboard

KEYDOES

TabMoves to the country trigger, then into the number field.

Enter / SpaceOpens the country list from the trigger.

Arrow keysMoves through the list; the search box filters it.

EscapeCloses the list and returns focus to the trigger.

Worth knowing

Country data is hand-maintained for 18 countries. It is accurate for those, but it is not libphonenumber and does not pretend to be.

Emits string, for example "+442071234567". Keyboard operation is covered by automated tests; screen readers have not been verified yet.