Guide
Options
Every option is optional. Defaults are chosen so the widget is correct without configuration.
| Option | Type | Default | What it does |
|---|---|---|---|
initialCountry |
string |
'auto' |
ISO code, or 'auto' to detect from lookupCountry, then time zone and language. |
fallbackCountry |
string |
'US' |
Used when detection finds nothing. |
lookupCountry |
() => Promise<string> |
— | Your own lookup (IP service, server header). Gets 1.5 s; non-ISO answers like GB-O are ignored. |
preferredCountries |
string[] |
[] |
Pinned to the top of the list. They never appear twice. |
onlyCountries |
string[] |
— | Restrict the list. |
excludeCountries |
string[] |
— | Remove countries from the list. |
separateDialCode |
boolean |
true |
Dial code on the button; the text holds the national number. |
formatAsYouType |
boolean |
true |
Group digits while typing. |
strict |
boolean |
true |
Refuse letters and digits beyond the longest possible number. |
allowExtensions |
boolean |
true |
Accept ext. 22, x22, #22 and localized forms. |
allowedTypes |
NumberType[] |
— | e.g. ['mobile']. Other types get reason: 'not_allowed_type'. |
placeholder |
'hint' | 'example' | 'mask' | 'off' |
'hint' |
hint shows the operator prefix and masks the rest: 50 xxx xxxx. Your own placeholder attribute always wins. |
placeholderType |
'mobile' | 'fixed' |
'mobile' |
Which example to base the placeholder on. |
hiddenInput |
string | { e164, country } |
— | Creates hidden inputs for plain form posts. |
locale |
string |
page lang |
Language for country names (from Intl.DisplayNames). |
strings |
object |
English | Translate the widget's own labels. |
messages |
object |
English | Validation messages per reason. |
flags |
'svg' | 'emoji' | 'none' |
'svg' |
SVG flags load lazily and work on Windows. |
searchable |
boolean |
true |
Search box in the country list. |
sheet |
'auto' | boolean |
'auto' |
Bottom sheet on screens up to 640 px wide. |
validateOn |
'blur' | 'input' | 'off' |
'blur' |
When to call setCustomValidity and set aria-invalid. |
theme |
'light' | 'dark' | 'auto' |
'auto' |
auto follows prefers-color-scheme. |
layout |
'wrap' | 'overlay' |
'wrap' |
wrap puts your input inside the widget's field. overlay leaves the input where it is, with its own styling, and floats the country button inside it. See Styling. |
onChange |
(result, instance) => void |
— | Same data as the dx:phonechange event. |
onCountryChange |
(country, instance) => void |
— | Same data as dx:countrychange. |
Validation reasons
| Reason | Meaning |
|---|---|
valid |
A real, dialable number for its country. |
empty |
Nothing entered. |
too_short / too_long |
Wrong number of digits for this country. |
invalid_length |
A length between valid ones that no number uses. |
invalid_country_code |
+999 and friends. |
invalid_number |
Right length, but no number in this plan starts like that. |
possible_local_only |
Missing its area code. |
not_allowed_type |
Valid, but not a type you allowed (e.g. a landline when you asked for mobile). |
Updated 12 Sep 2026