# PhoneInput

Page: /docs/components/phone-input

{/* Figma: Meridian → PhoneInput (docs 38:154, component set 21:8091). Spec: docs/design-system/meridian/phone-input.md */}

A phone number with its country in the same field: flag, dial code and a menu to change it. Any format while typing, tidied to the country’s format when people leave the field. 40 high with a 16 value and a 14 label, like Input. It is the phone field on every HubSpot form.

```tsx
import { PhoneInput } from "@commenda/meridian/ui/phone-input";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

export function PhoneCountries() {
	return (
		<Fields>
			<PhoneInput label="Phone number" defaultValue={{ country: "US", number: "(201) 555-0123" }} />
			<PhoneInput label="Phone number" defaultValue={{ country: "GB", number: "07700 900123" }} />
			<PhoneInput label="Phone number" defaultValue={{ country: "IN", number: "98765 43210" }} />
			<PhoneInput label="Phone number" defaultValue={{ country: "DE", number: "030 1234567" }} />
		</Fields>
	);
}
```

## Usage [#usage]

```tsx
import { PhoneInput } from "@commenda/meridian/ui/phone-input";

<PhoneInput
  label="Phone number"
  defaultValue={{ country: "US", number: "" }}
  onValidationChange={({ e164 }) => setPhone(e164)}
/>;
```

## Countries [#countries]

The country follows the visitor’s location by default. People change it from the flag. Each country shows its own example and format.

```tsx
import { PhoneInput } from "@commenda/meridian/ui/phone-input";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

export function PhoneCountries() {
	return (
		<Fields>
			<PhoneInput label="Phone number" defaultValue={{ country: "US", number: "(201) 555-0123" }} />
			<PhoneInput label="Phone number" defaultValue={{ country: "GB", number: "07700 900123" }} />
			<PhoneInput label="Phone number" defaultValue={{ country: "IN", number: "98765 43210" }} />
			<PhoneInput label="Phone number" defaultValue={{ country: "DE", number: "030 1234567" }} />
		</Fields>
	);
}
```

## Choosing a country [#choosing-a-country]

The country button opens a list with search: flag, country and dial code on the right. Typing a country name or a code (+44) filters it. Pasting a number that starts with a code switches the country. Click a flag above to try it.

## Formatting [#formatting]

Accept any format while typing: spaces, dashes, brackets, with or without the country code. No mask. When the field loses focus it is tidied to the country’s format, so the same number always looks the same.

## States [#states]

The same states as Input. Invalid says what is wrong, with an example in the country’s format.

```tsx
import { PhoneInput } from "@commenda/meridian/ui/phone-input";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

/** A form demo with its state name above it, full width so the field keeps its size. */
function Captioned({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex min-w-0 flex-col gap-2">
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
			{children}
		</div>
	);
}

export function PhoneStates() {
	return (
		<Fields>
			<Captioned label="with help">
				<PhoneInput
					label="Phone number"
					defaultValue={{ country: "US", number: "" }}
					placeholder="(201) 555-0123"
					description="Include the area code. We format it when you leave the field."
				/>
			</Captioned>
			<Captioned label="invalid">
				<PhoneInput
					label="Phone number"
					defaultValue={{ country: "US", number: "555-01" }}
					errorConfig={{
						message: "Enter a phone number like (201) 555-0123.",
						reveal: "immediate",
					}}
				/>
			</Captioned>
			<Captioned label="disabled">
				<PhoneInput
					label="Phone number"
					defaultValue={{ country: "US", number: "" }}
					placeholder="(201) 555-0123"
					disableConfig={{ isDisabled: true }}
				/>
			</Captioned>
		</Fields>
	);
}
```

## Anatomy [#anatomy]

Input’s frame: 40 tall, radius 8, 1px soft-pearl 400. Country button on the left: padding 12, flag 16, dial code 16, chevron 12; a 1px divider; then the number in 16. One focus ring around the whole field.

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (conditional) | `string` |  |
| `hideLabel` | `boolean` |  |
| `aria-label` (conditional) | `string` |  |
| `required` (conditional) | `true \| false` |  |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` |  |
| `sourceConfig` | `FieldSourceConfig` |  |
| `description` | `string` |  |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` |  |
| `disableConfig` | `DisableConfig` |  |
| `value` (conditional) | `PhoneValue` |  |
| `onValueChange` (conditional) | `(value: PhoneValue) => void` |  |
| `defaultValue` (conditional) | `PhoneValue` |  |
| `countryConfig` | `{ allowedCountries?: readonly CountryCode[]; }` |  |
| `onValidationChange` | `(details: PhoneValueDetails) => void` |  |

**`labelConfig` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `optionalLabel` (required) | `string` |  |

Do not supply: `help`.

**`labelConfig` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `help` (required) | `string` |  |

Do not supply: `optionalLabel`.

**`sourceConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `kind` (required) | `"entity" \| "record" \| "document"` |  |
| `label` (required) | `string` |  |
| `preview` (required) | `ReactNode` |  |
| `onOpen` (required) | `() => void` |  |
| `side` | `"top" \| "bottom"` |  |

**`errorConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `message` (required) | `string` |  |
| `reveal` | `"after-blur" \| "immediate"` |  |

**`disableConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `isDisabled` (required) | `boolean` |  |
| `reason` | `string` |  |

**`value` fields**

| Field | Type | Description |
| --- | --- | --- |
| `country` (required) | `"AC" \| "AD" \| "AE" \| "AF" \| "AG" \| "AI" \| "AL" \| "AM" \| "AO" \| "AR" \| "AS" \| "AT" \| "AU" \| "AW" \| "AX" \| "AZ" \| "BA" \| "BB" \| "BD" \| "BE" \| "BF" \| "BG" \| "BH" \| "BI" \| "BJ" \| "BL" \| "BM" \| "BN" \| "BO" \| "BQ" \| "BR" \| "BS" \| "BT" \| "BW" \| "BY" \| "BZ" \| "CA" \| "CC" \| "CD" \| "CF" \| "CG" \| "CH" \| "CI" \| "CK" \| "CL" \| "CM" \| "CN" \| "CO" \| "CR" \| "CU" \| "CV" \| "CW" \| "CX" \| "CY" \| "CZ" \| "DE" \| "DJ" \| "DK" \| "DM" \| "DO" \| "DZ" \| "EC" \| "EE" \| "EG" \| "EH" \| "ER" \| "ES" \| "ET" \| "FI" \| "FJ" \| "FK" \| "FM" \| "FO" \| "FR" \| "GA" \| "GB" \| "GD" \| "GE" \| "GF" \| "GG" \| "GH" \| "GI" \| "GL" \| "GM" \| "GN" \| "GP" \| "GQ" \| "GR" \| "GT" \| "GU" \| "GW" \| "GY" \| "HK" \| "HN" \| "HR" \| "HT" \| "HU" \| "ID" \| "IE" \| "IL" \| "IM" \| "IN" \| "IO" \| "IQ" \| "IR" \| "IS" \| "IT" \| "JE" \| "JM" \| "JO" \| "JP" \| "KE" \| "KG" \| "KH" \| "KI" \| "KM" \| "KN" \| "KP" \| "KR" \| "KW" \| "KY" \| "KZ" \| "LA" \| "LB" \| "LC" \| "LI" \| "LK" \| "LR" \| "LS" \| "LT" \| "LU" \| "LV" \| "LY" \| "MA" \| "MC" \| "MD" \| "ME" \| "MF" \| "MG" \| "MH" \| "MK" \| "ML" \| "MM" \| "MN" \| "MO" \| "MP" \| "MQ" \| "MR" \| "MS" \| "MT" \| "MU" \| "MV" \| "MW" \| "MX" \| "MY" \| "MZ" \| "NA" \| "NC" \| "NE" \| "NF" \| "NG" \| "NI" \| "NL" \| "NO" \| "NP" \| "NR" \| "NU" \| "NZ" \| "OM" \| "PA" \| "PE" \| "PF" \| "PG" \| "PH" \| "PK" \| "PL" \| "PM" \| "PR" \| "PS" \| "PT" \| "PW" \| "PY" \| "QA" \| "RE" \| "RO" \| "RS" \| "RU" \| "RW" \| "SA" \| "SB" \| "SC" \| "SD" \| "SE" \| "SG" \| "SH" \| "SI" \| "SJ" \| "SK" \| "SL" \| "SM" \| "SN" \| "SO" \| "SR" \| "SS" \| "ST" \| "SV" \| "SX" \| "SY" \| "SZ" \| "TA" \| "TC" \| "TD" \| "TG" \| "TH" \| "TJ" \| "TK" \| "TL" \| "TM" \| "TN" \| "TO" \| "TR" \| "TT" \| "TV" \| "TW" \| "TZ" \| "UA" \| "UG" \| "US" \| "UY" \| "UZ" \| "VA" \| "VC" \| "VE" \| "VG" \| "VI" \| "VN" \| "VU" \| "WF" \| "WS" \| "XK" \| "YE" \| "YT" \| "ZA" \| "ZM" \| "ZW"` |  |
| `number` (required) | `string` |  |

**`defaultValue` fields**

| Field | Type | Description |
| --- | --- | --- |
| `country` (required) | `"AC" \| "AD" \| "AE" \| "AF" \| "AG" \| "AI" \| "AL" \| "AM" \| "AO" \| "AR" \| "AS" \| "AT" \| "AU" \| "AW" \| "AX" \| "AZ" \| "BA" \| "BB" \| "BD" \| "BE" \| "BF" \| "BG" \| "BH" \| "BI" \| "BJ" \| "BL" \| "BM" \| "BN" \| "BO" \| "BQ" \| "BR" \| "BS" \| "BT" \| "BW" \| "BY" \| "BZ" \| "CA" \| "CC" \| "CD" \| "CF" \| "CG" \| "CH" \| "CI" \| "CK" \| "CL" \| "CM" \| "CN" \| "CO" \| "CR" \| "CU" \| "CV" \| "CW" \| "CX" \| "CY" \| "CZ" \| "DE" \| "DJ" \| "DK" \| "DM" \| "DO" \| "DZ" \| "EC" \| "EE" \| "EG" \| "EH" \| "ER" \| "ES" \| "ET" \| "FI" \| "FJ" \| "FK" \| "FM" \| "FO" \| "FR" \| "GA" \| "GB" \| "GD" \| "GE" \| "GF" \| "GG" \| "GH" \| "GI" \| "GL" \| "GM" \| "GN" \| "GP" \| "GQ" \| "GR" \| "GT" \| "GU" \| "GW" \| "GY" \| "HK" \| "HN" \| "HR" \| "HT" \| "HU" \| "ID" \| "IE" \| "IL" \| "IM" \| "IN" \| "IO" \| "IQ" \| "IR" \| "IS" \| "IT" \| "JE" \| "JM" \| "JO" \| "JP" \| "KE" \| "KG" \| "KH" \| "KI" \| "KM" \| "KN" \| "KP" \| "KR" \| "KW" \| "KY" \| "KZ" \| "LA" \| "LB" \| "LC" \| "LI" \| "LK" \| "LR" \| "LS" \| "LT" \| "LU" \| "LV" \| "LY" \| "MA" \| "MC" \| "MD" \| "ME" \| "MF" \| "MG" \| "MH" \| "MK" \| "ML" \| "MM" \| "MN" \| "MO" \| "MP" \| "MQ" \| "MR" \| "MS" \| "MT" \| "MU" \| "MV" \| "MW" \| "MX" \| "MY" \| "MZ" \| "NA" \| "NC" \| "NE" \| "NF" \| "NG" \| "NI" \| "NL" \| "NO" \| "NP" \| "NR" \| "NU" \| "NZ" \| "OM" \| "PA" \| "PE" \| "PF" \| "PG" \| "PH" \| "PK" \| "PL" \| "PM" \| "PR" \| "PS" \| "PT" \| "PW" \| "PY" \| "QA" \| "RE" \| "RO" \| "RS" \| "RU" \| "RW" \| "SA" \| "SB" \| "SC" \| "SD" \| "SE" \| "SG" \| "SH" \| "SI" \| "SJ" \| "SK" \| "SL" \| "SM" \| "SN" \| "SO" \| "SR" \| "SS" \| "ST" \| "SV" \| "SX" \| "SY" \| "SZ" \| "TA" \| "TC" \| "TD" \| "TG" \| "TH" \| "TJ" \| "TK" \| "TL" \| "TM" \| "TN" \| "TO" \| "TR" \| "TT" \| "TV" \| "TW" \| "TZ" \| "UA" \| "UG" \| "US" \| "UY" \| "UZ" \| "VA" \| "VC" \| "VE" \| "VG" \| "VI" \| "VN" \| "VU" \| "WF" \| "WS" \| "XK" \| "YE" \| "YT" \| "ZA" \| "ZM" \| "ZW"` |  |
| `number` (required) | `string` |  |

**`countryConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `allowedCountries` | `readonly CountryCode[]` |  |

## Best practices [#best-practices]

- One field with the country inside it. Never split the number into boxes.
- Default the country to the visitor’s location and let people change it. Countries always lead with their flag.
- Accept any format while typing and tidy on blur. Never block keys or force a mask.
- Validate with libphonenumber, and show an example in the chosen country’s format.
- Keep it optional on demo forms unless sales needs it. In code: type="tel" and autocomplete="tel"; send E.164 (+12015550123) to HubSpot.
- Source: Pathfinder PhoneInput. Meridian makes the field 40 tall with a 16 value and a 14 label.
