Available from v2.6.1
PhoneInputView
PhoneInputView is a phone input field that displays a country selector and accepts phone number input for a specific country.
Platform availability: iOS 17.0+
It includes the following features:
- Country selection with searchable list.
- Optional country flag icons via BackbaseCountryIcons framework.
- Configurable styles for normal, focused, error, and disabled states.
- Localized country names and phone codes.
When to use:
- Use PhoneInputView when you need to collect international phone numbers with country code selection.
- Consider using TextInput with phone number formatting when you only need to collect phone numbers for a single country.
- Consider using AddressForm when collecting phone numbers as part of a complete contact information form.
Import
import BackbaseDesignSystem
To use country icons, add the following to your Podfile:
pod 'BackbaseCountryIcons'
Visual reference
Phone Input Country Selector
|
Phone Input
|
API reference
PhoneInputView
A UIView component for phone number input with country code selection.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
countryCode |
String |
The currently selected country code (ISO 3166-1 alpha-2) |
|
countryCodeNumber |
String? |
The currently selected country phone code |
|
countryCore |
BackbaseCountryCore |
The country data provider |
|
countrySelectorStrings |
CountrySelectorConfiguration.Strings |
The country selection view strings |
|
errorLabel |
UILabel |
The label that displays error messages |
|
subscriberNumber |
String? |
The phone number entered by the user |
|
subscriberNumberMaxDigits |
Int |
The maximum number of digits for the phone input. Default is 12 |
|
textAlignment |
NSTextAlignment |
The alignment of the title label and input field |
|
textFieldVerticalSpacers |
CGFloat |
The vertical paddings of the text fields |
|
usesTextFieldVerticalSpacersForHeight |
Bool |
Whether to use vertical spacers for height calculation |
Style properties
|
Property |
Type |
Description |
|---|---|---|
|
clearErrorStyle |
Style<PhoneInputView>? |
The style when clearing an error |
|
countryCodeSelectionDisabledStyle |
Style<PhoneInputView>? |
The style when country selection is disabled |
|
defaultCountryCodeSelectedStyle |
Style<PhoneInputView>? |
The style when default country is set |
|
disabledStyle |
Style<PhoneInputView>? |
The style when disabled |
|
editingStyle |
Style<PhoneInputView>? |
The style when editing |
|
errorStyle |
Style<PhoneInputView>? |
The style when there is an error |
|
focusStyle |
Style<PhoneInputView>? |
The style in focused state |
|
normalStyle |
Style<PhoneInputView>? |
The style in normal state |
|
readOnlyStyle |
Style<PhoneInputView>? |
The style when read-only |
Initializers
- init(iconsProvider:delegate:style:)
|
Parameter |
Type |
Description |
|---|---|---|
|
iconsProvider |
CountryFlagProvider? |
Provider for country flag icons |
|
delegate |
PhoneInputViewDelegate? |
Delegate for phone input events |
|
style |
Style<PhoneInputView> |
Initial style for the component |
CountrySelectorConfiguration.Strings
|
Property |
Type |
Description |
|---|---|---|
|
countriesScreenAllCountriesHeader |
String |
The section header for all countries |
|
countriesScreenDismissButtonTitle |
String |
The dismiss button title |
|
countriesScreenSelectedCountryHeader |
String |
The section header for selected country |
|
countriesScreenTitle |
String |
The countries list screen title |
|
countryNotFoundMessage |
String |
The no data view message |
|
countryNotFoundTitle |
String |
The no data view title |
BackbaseCountryCore
The BackbaseCountryCore framework retrieves:
- Localized world country codes in ISO 3166-1 alpha-2 format.
- Country names.
- Country phone codes.
- Country icons (requires CountryFlagProvider implementation).
BackbaseCountryIcons
BackbaseCountryIcons adds country flag icon support to the PhoneInputView. Country icons are hidden by default.
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
subscriberNumberMaxDigits |
Int |
12 |
subscriberNumberMaxDigits
The subscriberNumberMaxDigits specifies the maximum number of digits the user can enter for the phone number.
let phoneInputView = PhoneInputView(
iconsProvider: BackbaseCountryIcons.countryFlagProvider,
delegate: self,
style: DesignSystem.shared.styles.phoneInputView
)
phoneInputView.subscriberNumberMaxDigits = 10
Configuring country selector strings
phoneInputView.countrySelectorStrings = CountrySelectorConfiguration.Strings(
countriesScreenAllCountriesHeader: "All available countries",
countriesScreenSelectedCountryHeader: "Current",
countriesScreenTitle: "Select a country",
countryNotFoundTitle: "Sorry",
countryNotFoundMessage: "No Result"
)
Usage
Basic usage
let phoneInputView = PhoneInputView(
iconsProvider: BackbaseCountryIcons.countryFlagProvider,
delegate: self,
style: DesignSystem.shared.styles.phoneInputView
)
Filtering available countries
phoneInputView.countryCore.worldCountries = ["AR", "BR", "EG", "ES", "IN", "LB", "NL"]
Retrieving phone number
var theSelectedCountryCodeNumber = phoneInputView.countryCodeNumber
var theEnteredPhoneNumber = phoneInputView.subscriberNumber
Adding a new country
phoneInputView.countryCore.worldCountries.append("IC")
phoneInputView.countryCore.phoneCodeProvider.setValue("+34", of: "IC")
// Set a custom name for non-standard countries
phoneInputView.countryCore.nameProvider.setValue("My Canary Islands", of: "IC")
// Set the flag
phoneInputView.countryCore.iconsProvider?.setValue(myImage, of: "IC")
Note: Failing to set a country name and/or phone code will result in debug errors being logged. These countries will not be displayed.
States and variants
Normal state
The default appearance when the input is not focused and has no errors.
let phoneInputView = PhoneInputView(
iconsProvider: BackbaseCountryIcons.countryFlagProvider,
delegate: self,
style: DesignSystem.shared.styles.phoneInputView
)
Focused state
The appearance when the phone number input field is actively focused for editing.
Error state
The appearance when validation fails or an error message is set.
Disabled state
The appearance when the input is disabled and not interactive.
Read-only state
The appearance when the input displays data but is not editable.
Country selection disabled state
The appearance when the country code selector is disabled but the phone input remains editable.
Customization
Styling
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.phoneInputView |
Main phone input style |
|
DesignSystem.shared.styles.phoneInputViewCountrySelectorView |
Country selector view style |
|
DesignSystem.shared.styles.countryListCountrySelectorView |
Country list view style |
Error handling
Validation errors can be displayed through the errorLabel and the errorStyle is applied to the component.
let phoneInputView = PhoneInputView(
iconsProvider: BackbaseCountryIcons.countryFlagProvider,
delegate: self,
style: DesignSystem.shared.styles.phoneInputView
)
// The errorStyle is applied automatically when validation fails
// Error messages are displayed in the errorLabel
Accessibility
The PhoneInputView component is built with accessibility in mind. See the information below for supported behaviors and configuration options to ensure a fully accessible experience for all users.
Accessibility configuration
|
Property |
Description |
Type |
|---|---|---|
|
accessibilityLabel |
The accessible label for the phone number input field |
String |
|
Country code selector |
Announced with format "%@, country code selector" where %@ is the country code |
Automatic |
Best practices
- The country code selector and phone number input field are announced appropriately by screen readers.
- Use localization to customize the accessibility announcements for the country code selector.
- Ensure error states are communicated through the error label which is accessible to VoiceOver.
Dependencies
- External dependencies: None
- Internal dependencies:
- BackbaseCountryCore: Country data provider
- BackbaseCountryIcons: Optional country flag icons
- TextInput: Used for phone number input field
- StateView: Used for empty search results
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
Tokens are defined in defaultTokens.json, which is integrated in the bundle of the framework, and can be customized by providing your own theme JSON file.
Token groups used by PhoneInputView:
- color/text-input/[state]: Input field colors for different states (via TextInput component)
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Text Input |
theme.color.text-input.[state].* |
See TextInput |
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Colors |
Theme.colors |
Text and background colors |
|
Typography |
DesignSystem.shared.fonts |
Input text fonts |
|
Spacing |
DesignSystem.shared.spacer.md |
Medium spacing |
|
Phone Input Style |
DesignSystem.shared.styles.phoneInputView |
Main phone input style |
|
Country Selector Style |
DesignSystem.shared.styles.phoneInputViewCountrySelectorView |
Country selector view style |
|
Country List Style |
DesignSystem.shared.styles.countryListCountrySelectorView |
Country list view style |
Localization
Override the following strings to customize the text for the PhoneInputView on the app level:
"DesignSystem.phoneInputView.placeholder" = "(555) 555-5555";
"DesignSystem.phoneInputView.accessibility.placeholder" = "Phone number";
"DesignSystem.phoneInputView.accessibility.countryCodeSelector" = "%@, country code selector";
"DesignSystem.countrySelector.allCountriesHeader" = "All";
"DesignSystem.countrySelector.selectedCountryHeader" = "Selected";
"DesignSystem.countrySelector.title" = "Select country code";
"DesignSystem.countrySelector.searchBarPlaceholderText" = "Search country";
"DesignSystem.countrySelector.countryNotFoundTitle" = "No Results Found";
"DesignSystem.countrySelector.countryNotFoundMessage" = "Sorry we couldn't find what you're looking for. Please try again.";
"DesignSystem.countrySelector.emptyCountriesTitle" = "Oops, nothing to show";
"DesignSystem.countrySelector.emptyCountriesMessage" = "Sorry, the list of countries is empty.";
See also
- TextInput - Text input component
- AddressForm - Address form component
- BackbaseCountryCore - Country data provider
- BackbaseCountryIcons - Country flag icons provider