PhoneInput
A phone number with its country in one field.
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.
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
import { PhoneInput } from "@commenda/meridian/ui/phone-input";
<PhoneInput
label="Phone number"
defaultValue={{ country: "US", number: "" }}
onValidationChange={({ e164 }) => setPhone(e164)}
/>;Countries
The country follows the visitor’s location by default. People change it from the flag. Each country shows its own example and format.
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
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
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
The same states as Input. Invalid says what is wrong, with an example in the country’s format.
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
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
| Prop | Type | Description |
|---|---|---|
labelConditional | string | From Pathfinder. |
hideLabel | boolean | From Pathfinder. |
aria-labelConditional | string | From Pathfinder. |
requiredConditional | true | false | From Pathfinder. |
labelConfig | ObjectView fields · 2 shapes | From Pathfinder. |
sourceConfig | FieldSourceConfigView fields | From Pathfinder. |
description | string | From Pathfinder. |
errorConfig | ObjectView fields | From Pathfinder. |
disableConfig | DisableConfigView fields | From Pathfinder. |
valueConditional | PhoneValueView fields | From Pathfinder. |
onValueChangeConditional | (value: PhoneValue) => void | From Pathfinder. |
defaultValueConditional | PhoneValueView fields | From Pathfinder. |
countryConfig | ObjectView fields | From Pathfinder. |
onValidationChange | (details: PhoneValueDetails) => void | From Pathfinder. |
labelConfigObject fields
Choose one of these 2 shapes. Don't combine fields the chosen shape excludes.
Option 1
| Field | Type | Description |
|---|---|---|
optionalLabelRequired | string |
Do not supply: help.
Option 2
| Field | Type | Description |
|---|---|---|
helpRequired | string |
Do not supply: optionalLabel.
sourceConfigObject fields
| Field | Type | Description |
|---|---|---|
kindRequired | "entity" | "record" | "document" | |
labelRequired | string | |
previewRequired | ReactNode | |
onOpenRequired | () => void | |
side | "top" | "bottom" |
errorConfigObject fields
| Field | Type | Description |
|---|---|---|
messageRequired | string | |
reveal | "after-blur" | "immediate" |
disableConfigObject fields
| Field | Type | Description |
|---|---|---|
isDisabledRequired | boolean | |
reason | string |
valueObject fields
| Field | Type | Description |
|---|---|---|
countryRequired | "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" | |
numberRequired | string |
defaultValueObject fields
| Field | Type | Description |
|---|---|---|
countryRequired | "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" | |
numberRequired | string |
countryConfigObject fields
| Field | Type | Description |
|---|---|---|
allowedCountries | readonly CountryCode[] |
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.