Available from 2.13.0
CountrySelector
CountrySelector is a screen that displays a searchable list of countries with flag icons, supporting both phone code and country code display modes.
Platform availability: iOS 17.0+
When to use:
- Use CountrySelector when users need to select a country from a searchable list, such as in address forms or phone number entry.
- Consider using a simple picker or dropdown for smaller, predefined lists of countries or regions.
Import
import BackbaseDesignSystem
import BackbaseCountryCore
import BackbaseCountryIcons
Visual reference
|
State |
Phone Code Mode |
Country Code Mode |
|---|---|---|
|
Normal |
|
|
|
Searching |
|
|
|
Not Found |
|
|
API reference
CountrySelectorFactory
Methods
- create(configuration:countryCore:strings:onSelectedCountry:)
- Creates a country selector view controller with the specified configuration.
|
Parameter |
Type |
Description |
|---|---|---|
|
configuration |
CountrySelectorConfiguration |
The configuration for the country selector |
|
countryCore |
CountryCoreFactory |
The country core factory instance |
|
strings |
CountrySelectorConfiguration.Strings |
The localized strings configuration |
|
onSelectedCountry |
(String) -> Void |
The callback invoked when a country is selected |
Returns: UIViewController - The configured country selector view controller
CountrySelectorConfiguration
Properties
|
Property |
Type |
Description |
|---|---|---|
|
countries |
[String] |
The array of world country codes in ISO 3166-1 alpha-2 format |
|
countryCode |
String |
The currently selected country code |
|
mode |
Mode |
The display mode (.phoneCode or .countryCode) |
CountrySelectorConfiguration.Mode
|
Case |
Description |
|---|---|
|
phoneCode |
Displays country flag, phone code, and country name |
|
countryCode |
Displays country flag, country name, and country code |
CountrySelectorConfiguration.Strings
Properties
|
Property |
Type |
Description |
|---|---|---|
|
countriesScreenAllCountriesHeader |
String? |
The section header for all available countries |
|
countriesScreenDismissButtonTitle |
String? |
The dismiss button title |
|
countriesScreenSearchBarPlaceholderText |
String? |
The search bar placeholder text |
|
countriesScreenSelectedCountryHeader |
String? |
The section header for selected country |
|
countriesScreenTitle |
String? |
The title for the country selection screen |
|
countryNotFoundMessage |
String? |
The message when no country is found |
|
countryNotFoundTitle |
String? |
The title when no country is found |
Usage
Basic usage
Create an instance of CountryCoreFactory:
let countryCore = CountryCoreFactory(iconsProvider: BackbaseCountryIcons.countryFlagProvider)
The iconsProvider parameter accepts an object that conforms to CountryFlagProvider. Use BackbaseCountryIcons.countryFlagProvider or a custom implementation.
Create a configuration
let configuration = CountrySelectorConfiguration(
countries: countryCore.worldCountries,
countryCode: selectedCountry,
mode: .countryCode
)
Parameters:
- The countries property is an array of world country codes in ISO 3166-1 alpha-2 format.
- The countryCode property is the current selected country code.
- The mode property determines the display layout. Defaults to .phoneCode if not specified.
Create strings configuration
let strings = CountrySelectorConfiguration.Strings(countriesScreenDismissButtonTitle: nil)
The initializer accepts default values, so parameters are optional.
Build and present the country selector
let countryListViewController = CountrySelectorFactory.create(
configuration: configuration,
countryCore: countryCore,
strings: strings,
onSelectedCountry: { selectedCountryCode in
print(selectedCountryCode)
}
)
Embed in a NavigationController and present:
let navigationController = NavigationController(
rootViewController: countryListViewController,
style: { navigation in
DesignSystem.shared.styles.modalNavigationController(navigation)
}
)
Accessibility
The CountrySelector component is built with accessibility in mind. See the information below for supported behaviors and configuration options.
Built-in accessibility
|
Feature |
Description |
|---|---|
|
VoiceOver |
The search bar supports VoiceOver for searching countries |
|
Cell accessibility |
Table cells are accessible with country names and codes read by VoiceOver |
|
Dynamic Type |
The component adjusts font sizes for Dynamic Type |
Best practices
- Test with VoiceOver enabled to ensure country selection is accessible.
- Verify that Dynamic Type settings scale appropriately for all text.
Dependencies
- External dependencies:
- BackbaseCountryCore: Core country data and factory
- BackbaseCountryIcons: Country flag icons provider
- Internal dependencies: NavigationController, StateView
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
This component uses semantic tokens only. See Semantic tokens below.
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Typography |
DesignSystem.shared.fonts |
Country name fonts |
|
Spacing |
DesignSystem.shared.spacer.md |
Medium spacing for layout |
|
Navigation Style |
DesignSystem.shared.styles.modalNavigationController |
Modal navigation controller style |
|
Table View Style |
DesignSystem.shared.styles.tableView |
Table view styling |
|
Table Cell Style |
DesignSystem.shared.styles.tableViewCell |
Table cell styling |
See also
- BackbaseCountryCore - Core country data provider
- BackbaseCountryIcons - Country flag icons provider
- NavigationController - Navigation controller for modal presentation