Forms
PhoneInput
A text input paired with a searchable country picker, showing a flag and dial code.
<UiPhoneInput />Model value
modelValue is the national number only — the dial code lives in the country selection, not in this string. Always controlled, matching Input, so bind it with v-model. Typing or pasting a + prefix switches the country picker for you and strips the prefix back out, which keeps the two halves from ever describing different countries.
Selected: +1
The number field (modelValue) is always controlled, matching Input; only the country selection supports an uncontrolled defaultCountry.
Country
country is the selected country's ISO 3166-1 alpha-2 code. Pass it to control the picker yourself — one-way to pin it, or with v-model:country to also hear about the reader's choice and the auto-switch a pasted dial code triggers. Omit it and the picker keeps the selection internally, starting from defaultCountry.
Typing or pasting a +<dial code> prefix into the number field auto-switches the country picker and strips the prefix, so +49 151 2345678 becomes Germany selected with 151 2345678 left in the field. Matching picks the longest dial code that's a prefix of what's typed, so single-digit codes (like +1) match as soon as that digit is entered — fine for the built-in list, but worth knowing if countries is overridden with codes that nest inside each other.
The picker trigger has no caret — it's still a role="combobox" opened by click or Enter/Space/Arrow keys, just without the visual affordance.
Default country
defaultCountry is the country the picker starts on when you're not controlling it, given as the same ISO code. It's only the initial value — the reader can still change it, and passing country overrides it entirely.
Countries
countries replaces the built-in twelve-entry list rather than adding to it, so include every option you want offered. Each entry is a name to list it under, an iso2 code used as the selection value, a dialCode without the leading +, and a flag image URL — the same shape the defaults use, which you can filter down if a subset is all you need.
The country flags are plain .svg files under the module's assets/flags folder, imported as URLs and passed straight to Avatar's src — the same fallback-to-initials/icon behavior applies if one ever fails to load.
countries fully replaces the built-in 12-country list rather than merging with it — include every option you want shown.
Show country
showCountry can drop the flag/dial-code picker entirely, leaving a plain number field with a leading phone icon. Reach for it when the country is already established elsewhere in the form — note that the + prefix then has nowhere to go, so the value you collect is the national number alone.
show-country={false} drops the flag/dial-code picker entirely in favor of a plain leading phone icon — the +<dial code> auto-detection is skipped too, since there's no country to switch.
Placeholder
placeholder is the hint shown in the number field while it's empty — the country picker keeps its flag either way. A formatted example of a local number does more work here than the word “Phone”, since the field takes the national part only.
Disabled
disabled switches off the number field and the country picker together, so neither half of the control can be changed while a form is saving or a record is read-only.
Variant
variant picks between the ringed outline field on the page background and the filled, ringless soft one, which gets its own section below.
`variant="soft"`
A filled, tinted background with no ring.
API Reference
Generated from the component's source — props, slots and emits as the component actually declares them.
Props
stringbooleantrueEmits
update:modelValue[value: string]update:country[value: string]Types
interface PhoneCountry {
/**
* Display name shown in the country list.
*/
name: string;
/**
* ISO 3166-1 alpha-2 country code, e.g. 'US'. Used as the selection value.
*/
iso2: string;
/**
* International dial code without the leading '+', e.g. '1'.
*/
dialCode: string;
/**
* URL of the flag image rendered next to the country, passed straight to `Avatar`'s `src`.
*/
flag: string;
}