PhoneCountryPicker displays a country flag trigger and searchable calling-code choices. Compose its two parts inside Dropdown. Your application supplies country data, owns the selected value, and handles the phone number.
Prepared choices
EachPhoneCountryOption has a unique value, a localized country label, a callingCode without the leading plus sign, and a flag node. Supply the country list in the order you want it displayed. The picker adds the plus sign to calling-code labels and keeps calling codes left to right next to right-to-left country names.
Search and selection
Search matches a substring of the country name, ignoring case and accents. It does not trim whitespace or match country values or calling codes. For example,united matches United Kingdom and United States, reunion matches Réunion, and +44 does not match a calling code.
The selected country appears first when it matches the query. Remaining matches retain their supplied order. A query that excludes the current selection also removes its row. Empty results show the supplied status message.
The search field receives focus when the popup opens. Arrow keys and typed letters navigate options. Enter chooses the highlighted matching result after typing, or the focused option. Enter with an empty query does not select a country while focus remains in the search field. Pointer selection calls onValueChange with the country value. The dropdown closes after selection and returns focus according to its focus settings. Search clears when the popup content unmounts.
Trigger and host integration
Trigger is a native button with a required accessible name. Its flag and chevron are decorative, and the selected country label becomes its accessible description. Pass the selected country to display its flag, or omit it for a world icon. Native attributes, event handlers, disabled, and the button ref reach the trigger.
Keep Dropdown.Root and Dropdown.Content in the host when coordinating controlled open state, popup placement, an explicit return-focus target, or application editing lifecycle. The shared parts use the root’s picker behavior. Use one root per selector to keep instances independent.
A phone library adapter maps the library’s country value, country-change callback, and disabled or read-only state onto this composition, and supplies its own translated trigger label. The adapter owns the library-specific country values and any subsequent focus on the phone input.
Labels
Supply localized country labels incountries and an accessible name on Trigger. The popup takes the trigger name unless a Dropdown.Title or an explicit label on Dropdown.Content names it. searchLabel defaults to Search and names both the search field and its placeholder. emptyLabel defaults to No results.
Front component renderer
In front components, the React and Preact renderers display the trigger, its flag, and its disabled state. Opening the popup is not supported yet: both renderers lack the native pointer data Dropdown reads, and in React the popup also fails while mounting because sandbox elements have nodataset, which stops the front component from rendering. These limitations do not affect normal React rendering.
Props
PhoneCountryPicker.Trigger
string
required
Required accessible name for the country selector button.
string | ((state: PopoverTriggerState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
number
default:"0"
How long to wait before closing the popover that was opened on hover.
Specified in milliseconds.Requires the
openOnHover prop.PhoneCountryOption
Prepared country whose flag is displayed and whose label describes the trigger. Omit it to show a world icon.
number
default:"300"
How long to wait before the popover may be opened on hover. Specified in milliseconds.Requires the
openOnHover prop.boolean
Disables the native trigger button.
string
ID of the trigger. In addition to being forwarded to the rendered element,
it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot
triggerId prop).boolean
default:"false"
Whether the popover should also open when the trigger is hovered.
CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
PhoneCountryPicker.Options
readonly PhoneCountryOption[]
required
Prepared choices with a unique value, localized label, calling code without a plus sign, and flag node. The supplied order is preserved after the matching selected country.
string
default:"No results"
Status message shown when no country names match. Defaults to No results.
(value: string) => void
required
Called with the chosen country value. The host owns the selected country and phone number.
string
default:"Search"
Accessible name and placeholder of the country search field. Defaults to Search.
string
Selected country value. Its row appears first only while it matches the search.