Components / Phone Input
Phone Input
International phone-number input with searchable country selector — flag, dial code, and country name in one composed control. Search by name, ISO code, or +dial-code · preferred countries pinned to top · emits a single E.164 value · keyboard-friendly · live-region announcements on country change.
forms v0.8.0
Playground
Examples
Default (US)
<cg-phone-input label="Phone" helper="We\u2019ll text a verification code" style="max-width:420px;"></cg-phone-input>Brazil with custom preferred list
<cg-phone-input label="Telefone" default-country="BR" preferred-countries='["BR","PT","US","DE"]' helper="Selecione o pa\u00eds e digite o n\u00famero" style="max-width:420px;"></cg-phone-input>Pre-filled E.164 value
<cg-phone-input label="Mobile" value="+447400123456" helper="Hydrates GB + national number from E.164" style="max-width:420px;"></cg-phone-input>Restricted to a few countries
<cg-phone-input label="Phone" only-countries='["US","CA","MX"]' helper="North-America only" style="max-width:420px;"></cg-phone-input>Sizes (md / lg)
<div style="display:flex;flex-direction:column;gap:16px;max-width:420px;"><cg-phone-input label="Medium (default)" size="md"></cg-phone-input><cg-phone-input label="Large" size="lg"></cg-phone-input></div>Error / Success
<div style="display:flex;flex-direction:column;gap:16px;max-width:420px;"><cg-phone-input label="Phone" error helper="Please enter a valid number"></cg-phone-input><cg-phone-input label="Phone" success value="+15551234567" helper="Looks good"></cg-phone-input></div>Disabled
<cg-phone-input label="Phone" disabled value="+15551234567" style="max-width:420px;"></cg-phone-input>Import
import { CgPhoneInput } from '@cognivo/components';// Or tree-shake: import '@cognivo/components/cg-phone-input';Per-component imports ship only that component (~8 kB gzip).
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | "" | Full E.164 number (e.g. +15551234567) |
country | string | "US" | ISO-3166-1 alpha-2 country code |
default-country | string | "US" | Initial country when value/country are empty |
label | string | "" | Floating label |
placeholder | string | "" | National-number placeholder (falls back to country format) |
helper | string | "" | Helper text below the field |
size | "md" | "lg" | "md" | Field size |
rounded | "none" | "sm" | "md" | "lg" | "lg" | Border radius |
preferred-countries | string[] | ["US","GB","BR","DE","FR","CA","AU","IN","JP","MX"] | ISO codes pinned to top of list |
only-countries | string[] | [] | Restrict picker to these ISO codes |
exclude-countries | string[] | [] | Hide these ISO codes from the list |
national-mode | boolean | false | Hide the dial code in the trigger (still emits E.164) |
disabled | boolean | false | Disabled state |
readonly | boolean | false | Readonly state |
error | boolean | false | Error state |
success | boolean | false | Success state |
loading | boolean | false | Loading state — replaces flag with spinner |
required | boolean | false | Required field |
name | string | "" | Form field name |
Events
| Event | Detail | Description |
|---|---|---|
cg-phone-input-change | {value, country, dialCode, nationalNumber, valid} | Number or country changed |
cg-phone-input-country-change | {country, dialCode} | User picked a different country |