country-icons
Available from 4.1.1
Overview
country-icons includes a collection of 265 country flag images and implements the CountryFlagProvider class from country-core. The module displays country flags alongside country names and phone codes in your app. It includes flag images in XML drawable format, ensuring perfect scaling across all Android devices and screen densities.
The flag provider resolves flags from drawable resources using a naming convention based on country codes. Flags are stored in the library's resources and can be overridden at runtime or by placing custom flags in your app's resources. The provider requires an Android Context to resolve drawable resources, so set the context before accessing flags.
It includes the following features:
- 265 country flag images in scalable XML drawable format
- Pre-configured flag provider implementation
- Automatic resource resolution from library resources
- Runtime flag override capabilities
- Seamless integration with country-core
API reference
BackbaseCountryFlagProvider
The BackbaseCountryFlagProvider class is the core implementation of the CountryFlagProvider abstract class.
Constructor
public constructor()
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. The flag is resolved from the library's drawable resources using the naming convention backbase_ic_flag_{countrycode}.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
Returns: DeferredDrawable - The flag drawable resource
Throws: IllegalStateException - When context is not set or flag is not found
- set(countryCode: String, value: DeferredDrawable)
- Sets a custom flag override for a specific country code. Use this to replace an existing flag or add support for a new region.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
|
value |
DeferredDrawable |
The DeferredDrawable to use as the flag |
Returns: —
Throws: —
Loading strategy
- Check exceptions: Custom overrides set via set operator.
- Library resources: Built-in flag collection from country-icons module.
- Throw exception: If flag not found and context is not set.
The two-tier loading strategy allows for maximum flexibility — you can override any flag or add new ones without modifying the library.
Usage
Basic setup
Create a flag provider instance and set the Android context.
import com.backbase.android.design.country.icons.BackbaseCountryFlagProvider
import com.backbase.android.design.country.provider.CountryNameProvider
import com.backbase.android.design.country.provider.CountryPhoneCodeProvider
// Create flag provider
val flagProvider = BackbaseCountryFlagProvider().apply {
context = requireContext() // Set Android context
}
// Use with other providers
val nameProvider = CountryNameProvider()
val phoneCodeProvider = CountryPhoneCodeProvider()
Getting flag images
Retrieve country flag drawables.
// Get a country flag
try {
val flagDrawable = flagProvider["US"]
// Use the DeferredDrawable to load the drawable
imageView.setImageDrawable(flagDrawable.resolve(context))
} catch (e: IllegalStateException) {
println("Flag not found or context not set: ${e.message}")
// Show fallback UI: country code text, placeholder image, etc.
}
Safe flag loading with fallbacks
Always provide fallback behavior for missing flags. Consider showing the country code as text or hiding the flag display entirely.
fun loadCountryFlag(context: Context, countryCode: String): Drawable? {
return try {
val flagProvider = BackbaseCountryFlagProvider().apply {
this.context = context
}
flagProvider[countryCode].resolve(context)
} catch (e: Exception) {
// Return a default flag or null for graceful fallback
ContextCompat.getDrawable(context, R.drawable.default_flag) // Your app's default flag
}
}
// Usage in UI
val flag = loadCountryFlag(requireContext(), "US")
flagImageView.setImageDrawable(flag)
flagImageView.visibility = if (flag == null) View.GONE else View.VISIBLE
Runtime flag overrides
Runtime overrides are useful for A/B testing flag designs, adding support for new regions, or updating flags due to political changes.
// Override a specific flag
val customUSFlag = DeferredDrawable.Resource(R.drawable.custom_us_flag)
flagProvider["US"] = customUSFlag
// Add a flag for a custom region
val customRegionFlag = DeferredDrawable.Resource(R.drawable.custom_region_flag)
flagProvider["XX"] = customRegionFlag
// Check if a flag has been overridden
if (flagProvider.exceptions.containsKey("US")) {
println("US flag has been customized")
}
Using with RecyclerView
Implement efficient flag loading in list views to prevent repeated resource resolution.
class CountryViewHolder(itemView: View) : RecyclerView.ViewHolder(itemView) {
private val flagImageView: ImageView = itemView.findViewById(R.id.flag_image)
private val flagProvider = BackbaseCountryFlagProvider().apply {
context = itemView.context.applicationContext
}
fun bind(countryCode: String) {
try {
val flagDrawable = flagProvider[countryCode]
flagImageView.setImageDrawable(flagDrawable.resolve(itemView.context))
} catch (e: Exception) {
flagImageView.visibility = View.GONE
}
}
}
Customization
Flag assets
The module includes 265 country flag images in XML drawable format to ensure that the flags look crisp on all screen densities, for example, mdpi, hdpi, xhdpi, xxhdpi, and xxxhdpi without requiring multiple image variants.
- Format: XML drawable for perfect scaling
- Naming convention: backbase_ic_flag_{countrycode} in lowercase
- Examples: backbase_ic_flag_us, backbase_ic_flag_de, backbase_ic_flag_jp
- Package: Embedded in the country-icons library module
Flag coverage
country-icons includes flags for all major countries and territories:
- All 249 countries from the country-core country list
- Additional regional flags and territories
- Historical and alternative flag variants for some countries
- Regional flags: United Nations, Antarctica, Central African Republic, Central American, Europe, North America, Oceania, South America, World
Bundle-level customization
Override individual flags
Add flag drawables to your main app module using the same naming convention:
YourApp/src/main/res/drawable/
├── backbase_ic_flag_us.xml # Override US flag
├── backbase_ic_flag_ca.xml # Override Canada flag
├── backbase_ic_flag_custom.xml # Add custom country flag
└── backbase_ic_flag_xx.xml # Add new region flag
Flag resolution looks in your app's resources first, then uses the built-in flags from the library. This allows you to override any flag without modifying the library.
Flag design guidelines
For best results, follow these design guidelines to ensure that custom flag assets are visually consistent with the built-in flags. This helps maintain uniform sizing and aspect ratios throughout the user interface.
- Dimensions: Maintain consistent aspect ratio
- Width: 28-40dp
- Height: 20-28dp
- Aspect Ratio: ~1.4:1, similar to most national flags
- Format: Use XML drawable format for vector scaling, or provide multiple densities: mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi
- Compatibility: Ensure flags work on both light and dark backgrounds
- Testing: Test with different screen densities and sizes
Error handling
The flag provider throws IllegalStateException if the context is not set or if a flag image is missing.
try {
val flagProvider = BackbaseCountryFlagProvider()
// Context must be set before accessing flags
flagProvider.context = requireContext()
val flag = flagProvider["XX"] // Unknown country code
} catch (e: IllegalStateException) {
// Handle missing flag or missing context
println("Flag error: ${e.message}")
// Show placeholder, hide flag view, etc.
}
Integration
With CountrySelector
Use the flag provider with the CountrySelector component.
import com.backbase.android.design.country.icons.BackbaseCountryFlagProvider
import com.backbase.android.design.country.provider.CountryNameProvider
import com.backbase.android.design.country.provider.CountryPhoneCodeProvider
val config = CountrySelectorConfiguration {
countryFlagProvider = BackbaseCountryFlagProvider().apply {
context = requireContext()
}
countryNameProvider = CountryNameProvider()
countryPhoneCodeProvider = CountryPhoneCodeProvider()
}
// Now CountrySelector will display flags alongside country names and phone codes
With custom views
Implement flag display in custom views or fragments.
class CountryInfoFragment : Fragment() {
private lateinit var flagProvider: BackbaseCountryFlagProvider
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
flagProvider = BackbaseCountryFlagProvider().apply {
context = requireContext()
}
}
fun displayCountry(countryCode: String) {
try {
val flagDrawable = flagProvider[countryCode]
binding.flagImageView.setImageDrawable(
flagDrawable.resolve(requireContext())
)
} catch (e: Exception) {
binding.flagImageView.visibility = View.GONE
}
}
}
Design tokens
The country-icons framework includes data-only classes and does not use design tokens directly. UI components that consume country-icons can apply appropriate design tokens to manage visual presentation. For more information, see the CountrySelector component.
Dependencies
External dependencies
- deferred-resources: For DeferredDrawable support
Internal dependencies
- country-core: Required for CountryFlagProvider base class
Framework requirements
- Android SDK: Minimum API level 26
- Android Resources: For drawable resource resolution
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-core - Core classes and data providers
- CountrySelector - UI component using flags