Forms

Phone Input

International phone field with a country selector, emitting E.164.

Import

tsx

import { PhoneInput } from "@cooud-ui/ui";

bash

npx cooud-ui add phone-input

Examples

Default

A searchable country selector (flag + dial code) fused to a national-number field that auto-groups digits for the selected country. `onChange` emits the composed E.164 string; the caret is preserved across reformatting.

Phone number

Pick a country and type — we compose the E.164 string.

tsx

function PhoneInputDemo() {
  const [phone, setPhone] = useState("");

  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <FieldLabel htmlFor="phone">Phone number</FieldLabel>
      <PhoneInput id="phone" value={phone} onChange={setPhone} />
      <FieldDescription>
        {phone ? (
          <span className="font-mono text-xs tabular-nums text-fg-secondary">{phone}</span>
        ) : (
          "Pick a country and type — we compose the E.164 string."
        )}
      </FieldDescription>
    </div>
  );
}

Default country & value

Seed an uncontrolled field from an E.164 string — the country is resolved by the longest matching dial code, and the national number is grouped to that country's pattern.

tsx

<PhoneInput defaultValue="+12025550142" aria-label="Phone number" />

Invalid

Set `invalid` and pair it with a FieldError for accessible validation feedback.

Phone number

Enter a complete phone number.

tsx

<Field>
  <FieldLabel htmlFor="phone">Phone number</FieldLabel>
  <PhoneInput id="phone" invalid defaultValue="+551198" aria-describedby="phone-err" />
  <FieldError id="phone-err">Enter a complete phone number.</FieldError>
</Field>

API Reference

Generated from the component's exported types.

PhoneInputProps

Extends Omit< InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange" | "type" >

Prop	Type	Default	Description
`value`	`string`	—	Controlled value as an E.164 string (e.g. `"+5511987654321"`). Pair with `onChange`.
`defaultValue`	`string`	—	Initial E.164 (or bare national) value for uncontrolled usage.
`onChange`	`(value: string) => void`	—	Called with the full E.164 string on every edit; empty string when no number is entered.
`defaultCountry`	`string`	`"BR"`	ISO 3166-1 alpha-2 code selected on first render. Defaults to `"BR"`.
`countries`	`PhoneCountry[]`	`DEFAULT_PHONE_COUNTRIES`	Overrides the built-in country list. Order controls the list order.
`invalid`	`boolean`	`false`	Marks the field invalid (red border/ring + `aria-invalid`).
`searchPlaceholder`	`string`	`"Search country…"`	Placeholder for the country search box inside the selector.
`emptyText`	`string`	`"No country found."`	Message shown when no country matches the search.
`label`	`string`	`"Phone number"`	Accessible name for the whole control and the number field. Defaults to `"Phone number"`.
`countryLabel`	`string`	`"Select country"`	Accessible name for the country selector trigger. Defaults to `"Select country"`.
`contentClassName`	`string`	—	Extra classes for the country selector popover.
`name`	`string`	—	Name for a hidden input carrying the E.164 value, so the field submits inside a form.