country-core
Available from v4.1.0
Overview
com.backbase.android.design:country-core is the foundational module for handling country-related data in Android applications. The module displays country names, retrieves international phone codes, and formats phone numbers in your app. It includes classes, implementations, and data for country names and phone codes for 249 countries worldwide using ISO 3166-1 alpha-2 country codes.
The module uses a provider-based architecture where each provider class handles a specific type of country data. Providers support runtime overrides, allowing you to customize values for specific countries without modifying the library. Country names are localised automatically based on the device's locale settings, while phone codes are stored in a built-in map for fast access.
- Localised country names using device locale
- International phone codes for all countries
- Extensible provider-based architecture
- Runtime override capabilities
- Phone number formatting utilities
API reference
CurrencyExtensions
Extension properties
-
Currency.iso4217FractionDigits
Returns the standard fraction digits for this currency according to the ISO 4217. This extension validates the system's Currency.defaultFractionDigits and returns the ISO 4217 value if they differ. This ensures consistent currency formatting across different Android versions and locales where system values might not match the standard.
val usd = Currency.getInstance("USD")
val fractionDigits = usd.iso4217FractionDigits // Returns 2
CountryProvider
The CountryProvider abstract class serves as the base class for country-related data access. It implements a generic mechanism for retrieving values by country code and supports runtime overrides through an exceptions map. Subclasses implement `valueOf` to define how values are retrieved from their data source.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
exceptions |
Map<String, T> |
Custom overrides set via the set operator |
Methods
-
get(countryCode: String)
Returns the value for a specific country code. Checks exceptions first, then calls valueOf.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
Returns: T, The value for the country code
Throws: —
-
set(countryCode: String, value: T)
Sets a custom value override for a specific country code. Use this to replace an existing value for a specific country code.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
|
value |
T |
The value to set as custom value |
Returns: —
Throws: —
-
valueOf(countryCode: String)
Abstract method that returns the value for a specific country code. Implement this method in subclasses to define how values are retrieved from the data source.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
Returns: T , The value for the country code
Throws: —
The exceptions property includes custom overrides that have been set using the set operator. The get operator checks exceptions first before calling valueOf, so custom overrides take precedence over default values.
CountryNameProvider
Returns localized country names based on the device locale. Uses Android's Locale.getDefault() to retrieve country names in the user's preferred language.
Constructor
public constructor()
Methods
-
get(countryCode: String)
Returns the localised country name for the given country code.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
Returns: The value for the country code
Throws: —
-
set(countryCode: String, value: String)
Sets a custom value override for a specific country code.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
|
value |
String |
The custom country name |
Returns: —
Throws: —
Country names are localised based on the user's device settings using Locale.getDefault(). Test with different locales to ensure proper display for your target markets.
CountryPhoneCodeProvider
Returns international phone codes for countries. Uses a built-in map of 249 countries with their respective phone codes in international format with '+' prefix.
Constructor
public constructor()
Methods
-
get(countryCode: String)
Returns the localised country name for the given country code.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
Returns: The international phone code with + prefix
Throws: IllegalArgumentException - When country code is unknown
-
set(countryCode: String, value: String)
Sets a custom phone code override for a specific country code.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
|
value |
String |
The custom country name |
Returns: —
Throws: —
Phone codes are loaded from a built-in map covering 249 countries. For better performance in list views, consider caching the codes you need frequently.
CountryFlagProvider
Abstract base class for accessing country flag images. This class requires an Android Context to resolve drawable resources. Subclasses implement valueOf to define how flag drawables are retrieved.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
context |
Context? |
Android context used to resolve drawable resources |
Methods
-
get(countryCode: String)
Returns the flag drawable for the given country code.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
Returns: DeferredDrawable - The flag drawable
Throws: —
-
set(countryCode: String, value: DeferredDrawable)
Sets a custom flag override for a specific country code
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
|
value |
DeferredDrawable |
The custom flag drawable |
Returns: —
Throws: —
PhoneFormatter
Interface for formatting phone numbers into a more human-readable format.
Methods
-
format(countryCode: String, subscriberNumber: String)
Formats a phone number based on the country code and subscriber number.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
|
subscriberNumber |
String |
The phone number without country code |
Returns: String? - Formatted phone number, or null if formatting fails
Throws: —
AndroidPhoneFormatter
Default implementation of PhoneFormatter that uses Android's PhoneNumberUtils.formatNumber under the hood.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
INSTANCE |
AndroidPhoneFormatter |
Singleton instance of the formatter |
Methods
-
format(countryCode: String, subscriberNumber: String)
Formats a phone number using Android's built-in phone number formatting.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
|
subscriberNumber |
String |
The phone number without country code |
Returns: String? - Formatted phone number, or null if formatting fails
Throws: —
WorldCountries
A LinkedHashSet containing all supported country codes (249 countries).
val WorldCountries: LinkedHashSet<String>
This set includes ISO 3166-1 alpha-2 country codes for all supported countries. Use this set to iterate over all available countries or filter country lists.
WorldRegions
A LinkedHashSet containing supported world region codes.
val WorldRegions: LinkedHashSet<String>
Available region codes:
- AQ - Antarctica
- CAF - Central African Republic
- CAS - Central America
- CEU - Europe
- CNA - North America
- COC - Oceania
- CSA - South America
- WW - World
Data providers
CountryNameProvider
Returns localised country names based on the device locale.
- Data source: Android system locale, Locale.getDefault() using country codes from WorldCountries
- Localisation: Automatically adapts to device language settings
- Fallback: System country names via Locale.displayCountry
- Customisation: Runtime overrides via set operator
Country names are localised based on the user's device settings. Test with different locales to ensure proper display for your target markets.
CountryPhoneCodeProvider
Returns international phone codes for countries.
- Data source: Built-in map of 249 countries with their respective phone codes
- Coverage: 249 countries with their respective phone codes
- Format: International format with '+' prefix, for example, "+1", "+44"
- Customisation: Runtime overrides via set operator
Phone codes are loaded from a built-in map at initialization. For better performance in list views, consider caching the codes you need frequently.
Usage
Basic usage
Create provider instances and access country data.
import com.backbase.android.design.country.provider.CountryNameProvider
import com.backbase.android.design.country.provider.CountryPhoneCodeProvider
import com.backbase.android.design.country.grouping.WorldCountries
// Create providers
val nameProvider = CountryNameProvider()
val phoneCodeProvider = CountryPhoneCodeProvider()
// Access country data
val countries = WorldCountries // 249 countries
Getting country information
Retrieve localised country names and phone codes.
// Get localised country name
val countryName = nameProvider["US"]
println(countryName) // "United States" or localised equivalent
// Get international phone code
val phoneCode = phoneCodeProvider["US"]
println(phoneCode) // "+1"
Runtime overrides
Override country names or phone codes for specific countries.
// Override country name
nameProvider["US"] = "Custom Country Name"
// Override phone code for a new region
phoneCodeProvider["XX"] = "+999"
// Check if override exists
if (nameProvider.exceptions.containsKey("US")) {
println("US has a custom name override")
}
Batch processing
Process all countries efficiently.
fun processAllCountries() {
val nameProvider = CountryNameProvider()
val phoneCodeProvider = CountryPhoneCodeProvider()
for (countryCode in WorldCountries) {
val name = nameProvider[countryCode]
val phoneCode = phoneCodeProvider[countryCode]
// Process country data
println("$countryCode: $name ($phoneCode)")
}
}
Phone number formatting
Format phone numbers using the built-in formatter.
import com.backbase.android.design.country.formatter.AndroidPhoneFormatter
val formatter = AndroidPhoneFormatter.INSTANCE
// Format a US phone number
val formatted = formatter.format("US", "5551234567")
println(formatted) // "(555) 123-4567" - format may vary by locale
Custom country lists
Filter WorldCountries to create custom country lists.
// Create a list of European countries only
val europeanCountries = WorldCountries.filter { countryCode ->
listOf("DE", "FR", "IT", "ES", "NL", "BE", "AT", "CH").contains(countryCode)
}
println("European countries: ${europeanCountries.size}") // 8
Error handling
The CountryPhoneCodeProvider throws IllegalArgumentException if a country code is unknown.
try {
val phoneCode = phoneCodeProvider["XX"] // Unknown country code
} catch (e: IllegalArgumentException) {
println("Phone code not found: ${e.message}")
// Handle missing phone code - show error, use default, etc.
}
Accessibility
The country-core framework includes data-only classes and does not have specific accessibility requirements. UI components that consume country-core should apply appropriate accessibility features:
- Use country names in the user's preferred language
- Include alternative text for flag images when using CountryFlagProvider
- Ensure phone codes are clearly readable and formatted consistently
Integration
With country-icons
country-core works independently but integrates with country-icons to access flag images. country-icons depends on country-core and extends the CountryFlagProvider class defined in Core. For more information on the flag-specific features, see the country-icons documentation.
import com.backbase.android.design.country.provider.CountryNameProvider
import com.backbase.android.design.country.provider.CountryPhoneCodeProvider
import com.backbase.android.design.country.icons.BackbaseCountryFlagProvider
// Complete setup with flag provider
val flagProvider = BackbaseCountryFlagProvider().apply {
context = requireContext()
}
// Now you have access to all country data including flags
val name = nameProvider["US"]
val phoneCode = phoneCodeProvider["US"]
val flag = flagProvider["US"]
With CountrySelector
Use providers with the CountrySelector component.
import com.backbase.android.design.country.provider.CountryNameProvider
import com.backbase.android.design.country.provider.CountryPhoneCodeProvider
import com.backbase.android.design.country.icons.BackbaseCountryFlagProvider
val config = CountrySelectorConfiguration {
countryFlagProvider = BackbaseCountryFlagProvider().apply {
context = requireContext()
}
countryNameProvider = CountryNameProvider()
countryPhoneCodeProvider = CountryPhoneCodeProvider()
}
Dependencies
External dependencies
- deferred-resources: For DeferredDrawable support in CountryFlagProvider
Framework requirements
- Android SDK: Minimum API level 26
- Java/Kotlin: Standard library for Locale and collections
Module relationship
country-core defines the CountryFlagProvider abstract class, while country-icons implements the concrete class with actual flag assets. This separation allows country-core to work independently for text-only scenarios.
country-icons
↓ depends on
country-core
↓ depends on
Android SDK + deferred-resources
See also
- country-icons - Flag images and provider implementation
- CountrySelector - UI component for country selection