Available from v2.13.0
BackbaseCountryIcons
BackbaseCountryIcons provides a comprehensive collection of country flag images and a complete implementation of the CountryFlagProvider protocol from BackbaseCountryCore. It includes 265 high-quality country flag images in PDF format, ensuring perfect scaling across all iOS devices.
It includes the following features:
- 265 country flag images in scalable PDF format.
- Pre-configured shared flag provider instance.
- Automatic fallback from main bundle to library bundle.
- Runtime flag override capabilities.
- Seamless integration with BackbaseCountryCore.
API reference
BackbaseCountryFlagProvider
The BackbaseCountryFlagProvider class is the core implementation of the CountryFlagProvider protocol from BackbaseCountryCore framework.
Methods
- getValue(of:)
- Returns: UIImage? the flag image from the country code
- Throws: CountryCoreError.flagMissing , when flag is not found.
|
Parameter |
Type |
Description |
|---|---|---|
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
- setValue(_:of:)
- Used to override the image for a specific country during the run time.
|
Parameter |
Type |
Description |
|---|---|---|
|
value |
UIImage |
The UIImage to use as the flag |
|
countryCode |
String |
ISO 3166-1 alpha-2 country code |
Properties
|
Parameter |
Type |
Description |
|---|---|---|
|
exceptions |
[String: UIImage] |
Custom overrides set via setValue |
The exceptions property includes custom overrides that have been set using the setValue method. Always check the exceptions property for these overrides before calling getValue to ensure you are accessing the correct value.
Loading Strategy
1. Check exceptions: Custom overrides set via setValue
2. Main bundle override: App-specific flag images
3. Library bundle: Built-in flag collection
4. Throw error: If flag not found in any location
The three-tier loading strategy allows for maximum flexibility - you can override any flag or add new ones without modifying the library.
BackbaseCountryIcons.countryFlagProvider
A pre-configured, ready-to-use flag provider instance.
The flag provider is available as a shared instance for convenient, consistent access throughout your app.
public let countryFlagProvider: CountryFlagProvider = BackbaseCountryFlagProvider()
Usage
Basic setup
Always use the shared instance BackbaseCountryIcons.countryFlagProvider rather than creating your own BackbaseCountryFlagProvider instances.
import BackbaseCountryCore
import BackbaseCountryIcons
// Use the shared flag provider instance
let countryCore = CountryCoreFactory(
iconsProvider: BackbaseCountryIcons.countryFlagProvider
)
Getting flag images
// Get a country flag
do {
let flagImage = try countryCore.iconsProvider?.getValue(of: "US")
if let flag = flagImage {
imageView.image = flag
}
} catch CountryCoreError.flagMissing(let code) {
print("Flag not found for country: \(code)")
// Show fallback UI (country code text, placeholder image, etc.)
} catch {
print("Unexpected error: \(error)")
}
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.
func loadCountryFlag(for countryCode: String) -> UIImage? {
do {
return try BackbaseCountryIcons.countryFlagProvider.getValue(of: countryCode)
} catch {
// Return a default flag or nil for graceful fallback
return UIImage(named: "default_flag") // Your app's default flag
}
}
// Usage in UI
let flag = loadCountryFlag(for: "US")
flagImageView.image = flag
flagImageView.isHidden = (flag == nil) // Hide if no flag available
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
if let customUSFlag = UIImage(named: "custom_us_flag") {
BackbaseCountryIcons.countryFlagProvider.setValue(customUSFlag, of: "US")
}
// Add a flag for a custom region
if let customRegionFlag = UIImage(named: "custom_region_flag") {
BackbaseCountryIcons.countryFlagProvider.setValue(customRegionFlag, of: "XX")
}
// Check if a flag has been overridden
if BackbaseCountryIcons.countryFlagProvider.exceptions["US"] != nil {
print("US flag has been customized")
}
Customisation
Flag assets
The module includes 265 country flag images in PDF format to ensure that the flags look crisp on all screen densities, for example, 1x, 2x, 3x, and sizes without requiring multiple image variants.
- Format: Vector PDF for perfect scaling
- Naming Convention: backbase_ic_flag_{countrycode}
- Examples: backbase_ic_flag_us, backbase_ic_flag_de, backbase_ic_flag_jp
- Bundle: Embedded in the BackbaseCountryIcons framework
Flag coverage
BackbaseCountryIcons includes flags for all major countries and territories:
- All 249 countries from BackbaseCountryCore's country list
- Additional regional flags and territories
- Historical and alternative flag variants for some countries
Bundle-level customisation
Override individual flags
Add flag images to your main app bundle using the same naming convention:
YourApp.app/
├── backbase_ic_flag_us.pdf // Override US flag
├── backbase_ic_flag_ca.pdf // Override Canada flag
├── backbase_ic_flag_custom.pdf // Add custom country flag
└── backbase_ic_flag_xx.pdf // Add new region flag
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-40 points
- Height: 20-28 points
- Aspect Ratio: ~1.4:1, similar to most national flags
- Format: Use PDF format for vector scaling
- Compatibility: Ensure flags work on both light and dark backgrounds
- Testing: Test with different screen densities such as 1x, 2x and 3x
Error handling
The flag provider throws CountryCoreError.flagMissing if a flag image is missing. For details on the loading order, see Loading strategy.
do {
let flag = try BackbaseCountryIcons.countryFlagProvider.getValue(of: "XX")
} catch CountryCoreError.flagMissing(let code) {
// Handle missing flag - show placeholder, hide flag view, etc.
}
Integration
With CountrySelector
import BackbaseDesignSystem
// Complete country selector with flags
let countryCore = CountryCoreFactory(
iconsProvider: BackbaseCountryIcons.countryFlagProvider
)
let configuration = CountrySelectorConfiguration(
countries: countryCore.worldCountries,
countryCode: "US",
mode: .countryCode
)
let countrySelector = CountrySelectorFactory.create(
configuration: configuration,
countryCore: countryCore,
strings: CountrySelectorConfiguration.Strings(),
onSelectedCountry: { selectedCode in
// Access all country data including flag
let name = try? countryCore.nameProvider.getValue(of: selectedCode)
let phoneCode = try? countryCore.phoneCodeProvider.getValue(of: selectedCode)
let flag = try? countryCore.iconsProvider?.getValue(of: selectedCode)
}
)
With table/collection views
Implement image caching for table and collection views to prevent repeated file system access and improve scrolling performance.
func configure(with countryCode: String, countryCore: CountryCoreFactory) {
// Load flag with caching
if let cachedFlag = FlagCache.shared.flag(for: countryCode) {
flagImageView.image = cachedFlag
} else {
do {
let flag = try countryCore.iconsProvider?.getValue(of: countryCode)
flagImageView.image = flag
FlagCache.shared.setFlag(flag, for: countryCode)
} catch {
flagImageView.image = nil
flagImageView.isHidden = true
}
}
// Load other country data
countryNameLabel.text = try? countryCore.nameProvider.getValue(of: countryCode)
phoneCodeLabel.text = try? countryCore.phoneCodeProvider.getValue(of: countryCode)
}
Design tokens
The BackbaseCountryIcons framework includes data-only classes and does not use design tokens directly. UI components that consume BackbaseCountryIcons can apply appropriate design tokens to manage visual presentation. For more information, see the CountrySelector and PhoneInput components.
Dependencies
- BackbaseCountryCore: Required for CountryFlagProvider protocol and error types
- UIKit: For UIImage support
- Foundation: Core iOS framework
Module relationship
BackbaseCountryCore defines the CountryFlagProvider protocol, while BackbaseCountryIcons provides the concrete implementation with actual flag assets. This separation allows BackbaseCountryCore to work independently for text-only scenarios.
BackbaseCountryIcons
↓ (depends on)
BackbaseCountryCore
↓ (depends on)
Foundation + UIKit
See also
- BackbaseCountryCore - Core protocols and data providers
- CountrySelector - UI component using flags
- PhoneInput - Phone input with flag display