Phone Input React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Phone Input is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import PhoneInput from @/components/ui/phone-input.

import { useState } from "react"
import { PhoneInput, type PhoneDetails } from "@/components/ui/phone-input"

export function ContactForm() {
  const [phone, setPhone] = useState("")
  const [details, setDetails] = useState<PhoneDetails | null>(null)
  const [touched, setTouched] = useState(false)

  return (
    <form className="flex flex-col gap-4">
      <PhoneInput
        name="phone"
        label="Phone"
        description="Only interested buyers will call you."
        defaultCountry="US"
        preferredCountries={["US", "CA", "GB"]}
        value={phone}
        onValueChange={(e164, info) => {
          setPhone(e164)
          setDetails(info)
        }}
        onBlur={() => setTouched(true)}
        error={touched && details?.national && !details.valid ? "The phone number is not valid" : undefined}
        showValidity
        required
      />
    </form>
  )
}

Props

• defaultCountrydefault "RO"
  CountryCode

  The starting country (ISO 3166 code such as US, GB or RO) when the value does not name one. An unknown code falls back to RO.

• countrySelectdefault true
  boolean

  false fixes the country: no picker, the calling code shows as a text prefix ("+40"); a pasted "+40 712…" or "0040 712…" still fills in the national digits.

• placeholderdefault ""
  string

  Empty shows the country's example mobile number from libphonenumber-js (712 034 567 for RO), formatted like the field formats and without the calling code; it follows the country.

• showValiditydefault false
  boolean

  A green check pops in (scale 0.8 to 1, snappy spring) while the number is valid, with a visually hidden label.

• localedefault ""
  string

  The language of the country names (Intl.DisplayNames) and of the list order, e.g. "en-US" or "de-DE". Empty uses the UIProvider locale, then the nearest LocaleProvider, then the page. English names stay searchable in every locale.

• labeldefault ""
  ReactNode

  Renders the field anatomy around the box, linked with htmlFor. Leave it empty for a bare field (then pass aria-label).

• descriptiondefault ""
  ReactNode

  Helper text under the box, linked with aria-describedby.

• errordefault ""
  ReactNode

  Replaces the description with the animated error and sets invalid (red ring, aria-invalid on the number input).

• requireddefault false
  boolean

  The red * after the label and required on the number input.

• invaliddefault false
  boolean

  The invalid look and aria-invalid without a message.

• disableddefault false
  boolean

  Dims to 50%, blocks typing and the country list, and keeps the hidden input out of the form.

• readOnlydefault false
  boolean

  The number stays visible and selectable, the list never opens, no hover tint.

• sizedefault "md"
  "sm" | "md" | "lg"

  32 / 40 / 48px boxes (md grows to 44px on touch screens), 16px text on phones so iOS never zooms.

• variantdefault "soft"
  "soft" | "outline" | "underline" | "ghost"

  The box look, shared with every field.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner radius per size (the button's scale); the flag button follows it. Ignored by underline.

• responsivedefault true
  boolean

  The country list is a bottom sheet with search below 768px; false keeps the popover.

• defaultOpendefault false
  boolean

  Opens the country list on mount. open / onOpenChange control it.

• value
  string

  The E.164 number ("+40712345678"), controlled. A value for another country switches the country. "" while empty or incomplete.

• defaultValuedefault ""
  string

  The starting number, uncontrolled: E.164 ("+40712345678", which also picks the country), or national digits for the default country.

• onValueChange
  (e164: string, details: PhoneDetails) => void

  Fires on every edit: the E.164 number once it is possible, else "" with the details, so a form can say incomplete. PhoneDetails = { country?: CountryCode; national: string; international: string; valid: boolean; possible: boolean }.

• country
  CountryCode

  The selected country, controlled. Pair it with onCountryChange.

• onCountryChange
  (country: CountryCode) => void

  Fires when the list, the typeahead on the flag button or a typed calling code changes the country.

• countries
  CountryCode[]

  Limits the list (and the countries a typed calling code may pick). All 245 by default, virtualized.

• preferredCountriesdefault "["RO", "MD"]"
  CountryCode[]

  Shown first under the Suggested heading; an empty array drops the headings.

• renderFlag
  (country: CountryCode) => ReactNode

  Custom flags (SVGs from your app) in the button and the list. By default the emoji flag; on Windows, which has no flag emoji, the ISO code in a small chip after mount.

• labels
  Partial<PhoneInputLabels>

  Every visible and spoken string: the flag button's name ("Country: Romania +40") and the sheet title, the search placeholder, the empty text, the group headings, the example format read after the field and the validity text.

• namedefault ""
  string

  Renders a hidden input with this name and the E.164 value, so FormData gets the clean number (disabled fields are not submitted). The readout under the demo shows the pair.

• id
  string

  The number input's id (useId() by default; the flag button gets `${id}-country`).

• container
  HTMLElement | null

  Where the country list is portaled; document.body by default.

• open
  boolean

  The country list's open state, controlled; with onOpenChange.

• onOpenChange
  (open: boolean) => void

  Fires when the country list opens or closes.

• autoCompletedefault "tel-national"
  string

  On the number input. A full number autofilled with tel ("+40 712…") is detected like a paste.

• inputModedefault "tel"
  "tel" | "numeric" | "decimal" | "text" | "email" | "url" | "search" | "none"

  The keypad on touch screens: tel has + and the digits; numeric only digits.

• enterKeyHintdefault "next"
  "next" | "done" | "go" | "send" | "search" | "enter" | "previous"

  The label of the on-screen Enter key; use done on the last field of a form.

• fieldProps
  Partial<FieldProps>

  Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.

• classNames
  Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "country" | "flag" | "code" | "chevron" | "input" | "validity" | "content", string>>

  Extra classes for the field parts, the box, the flag button and its parts, the number input, the check and the list.

• ref
  RefObject<HTMLInputElement | null> or (node) => void

  The number input. Every other native prop lands on it too: onBlur, autoComplete ("tel-national"), inputMode ("tel"), enterKeyHint ("next"), aria-*. The input holds formatted national digits, so with react-hook-form use Controller (value / onValueChange). The default metadata is libphonenumber-js min (lengths and leading digits); import from libphonenumber-js/max in your copy for stricter number-type checks at a larger size.

Parts

FAQ

Used in

More React input components