
Lightweight, fully customizable country and phone-code picker with searchable lists, flag artwork, real-time phone formatting and validation, multi-selection, region filters, and verification hooks.
📖 Documentation: ezekielwachira.github.io/Country-Code-Picker — guides, recipes and the API reference.
A lightweight, fully customizable Compose Multiplatform library for Android and iOS: country selection, country code selection, phone number validation, and real-time formatting based on country-specific rules — one API, written once in common code.
The library ships two layers:
PhoneNumberInput — the original phone-number component. It now
runs on the Country Picker foundation internally, so existing call sites keep working unchanged; see
Migrating from PhoneNumberInput if you want to move to the newer
API.The Signature style, with flagcdn.com flags, on iOS. The same code renders it on Android.
![]() Country sheet |
![]() Phone field |
![]() Multiple selection |
![]() "Did you mean" |
![]() Dark mode |
![]() Fields and pills |
Every option above — presets, accent, density, list style, flag shape, format and frame — is a live control in the sample app's Showcase tab.
CountryPickerStyle (colors, shapes, type, motion, elevation,
layout, haptics) with Signature, Material, Cupertino and Minimal presets, three densities, light and
dark, and a brand accent in one lineCountryPickerPanel inlinecommonMain code via Compose Multiplatform+254… adopts its own countryPhoneNumberVerificationHandler
CountryPickerState / PhoneState to the caller for external control✓ Mobile badge once the number is valid+254 never
renders as 254+
The library is published to Maven Central
as io.github.ezekielwachira:ccp. In a Kotlin Multiplatform module, add it to commonMain:
kotlin {
sourceSets {
commonMain.dependencies {
implementation("io.github.ezekielwachira:ccp:0.3.0")
}
}
}In an Android-only module, as before:
dependencies {
implementation("io.github.ezekielwachira:ccp:0.3.0")
}mavenCentral() is in most projects' repository list already; nothing else to add. Gradle picks the
right artifact per target (ccp-android, ccp-iosarm64, ccp-iossimulatorarm64).
Nothing beyond the Gradle dependency. The phone-number engine (libPhoneNumber-iOS) is compiled into the library's iOS klib, so there is no CocoaPod, Swift package or linker flag to add, and an app that also uses libPhoneNumber-iOS directly links fine — the embedded copy's symbols are prefixed.
Host the shared UI the usual Compose Multiplatform way, from your iOS source set:
fun MainViewController(): UIViewController = ComposeUIViewController {
var country by remember { mutableStateOf<Country?>(null) }
CountrySelector(selectedCountry = country, onCountrySelected = { country = it })
}iosApp/ is a complete example: open iosApp/iosApp.xcodeproj in Xcode and run the
CCP Sample scheme. It builds the shared :sample module — the same demo the Android
:app runs.
0.3.0 is the first release on Maven Central. Earlier versions were published only through JitPack,
under a different coordinate, and are Android-only (JitPack builds on Linux, which cannot produce the
iOS artifacts). To stay on one of those, add the JitPack repository to your root settings.gradle.kts:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}dependencies {
implementation("com.github.EzekielWachira:Country-Code-Picker:0.2.0")
}libphonenumber ships three metadata blobs. The picker only ever reaches PhoneNumberUtil and
AsYouTypeFormatter, which need one of them:
| Blob | Size | Needed |
|---|---|---|
PhoneNumberMetadataProto |
~235 KB | yes |
ShortNumberMetadataProto |
~75 KB | only by ShortNumberInfo — unused here |
PhoneNumberAlternateFormatsProto |
~23 KB | only by PhoneNumberMatcher — unused here |
If your app does not use those APIs either, drop the two unused blobs:
android {
packaging {
resources {
excludes += setOf(
"/com/google/i18n/phonenumbers/data/ShortNumberMetadataProto*",
"/com/google/i18n/phonenumbers/data/PhoneNumberAlternateFormatsProto*",
)
}
}
}The sample app in this repository ships with these exclusions applied, so CI builds and tests the
configuration rather than only documenting it. A build task (verifyPhoneNumberMetadataFootprint)
fails the library's own build if it ever starts using an API that would need them back.
Everything below lives under com.ezzy.ccp.countrypicker — the country model, search, state, theme
and UI are all reusable independently of phone numbers. A sample screen reproducing the flow below is
in YourDetailsSampleScreen,
and every state described here has a matching @Preview in
CountryPickerPreviews.kt.
var country by rememberSaveable { mutableStateOf<Country?>(null) }
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
label = UiText.of("Country of residence"),
)CountrySelector is fully controlled: selectedCountry is the source of truth, and the component never
mutates it — a selection only ever arrives through onCountrySelected, carrying the complete Country
(ISO alpha-2/3, dial code, region, flag), never just a name or a code.
Same sheet, same behavior, smaller footprint — pick with variant:
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
variant = CountrySelectorVariant.Compact, // 🇩🇪 Germany ˅
label = null,
)
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
variant = CountrySelectorVariant.FlagOnly, // 🇩🇪 ˅
label = null,
)The flag-only variant has no visible text, so it carries its own content description automatically —
"Selected country: Germany. Double tap to change." — no extra wiring needed.
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
variant = CountrySelectorVariant.DialCode, // 🇰🇪 +254 ˅
label = null,
config = CountryPickerDefaults.phoneConfig(),
)In practice you won't call this directly — PhoneNumberField already embeds
it next to the number input.
val phoneState = rememberPhoneNumberFieldState(initialCountry = kenya)
PhoneNumberField(
state = phoneState,
onValueChange = { value: PhoneNumberValue ->
value.e164Number // "+254712345678", or null while unparseable
value.internationalNumber // "+254 712 345678"
value.isValid // true only for a real, dialable number
},
)PhoneNumberValue.e164Number comes from libphonenumber, not from concatenating a dial code onto typed
digits — that concatenation is wrong for any region with a national trunk prefix (a UK mobile typed as
07400 123456 is +447400123456, not +4407400123456). Never rebuild it by hand.
Changing the selected country keeps the digits the user already typed, reformats them for the new region, and revalidates — a number valid in one country is never carried over as still-valid in another.
when (phoneState.value.validity) {
PhoneNumberValidity.Empty -> Unit // nothing typed; show nothing
PhoneNumberValidity.Incomplete -> Unit // still typing; show nothing
PhoneNumberValidity.Valid -> submit()
else -> showError(PhoneNumberValidator.errorMessage(phoneState.value))
}PhoneNumberField already shows/hides its own error text this way; reach for PhoneNumberValidator
directly only when you need the result before the user submits.
The library ships no verification backend on purpose — implement the one contract against your own SMS/Firebase/whatever provider:
class MyVerificationHandler(private val api: MyAuthApi) : PhoneNumberVerificationHandler {
override suspend fun requestVerification(phoneNumber: PhoneNumberValue) =
api.sendCode(phoneNumber.e164Number!!).toRequestResult()
override suspend fun verifyCode(verificationId: String, code: String) =
api.checkCode(verificationId, code).toVerificationResult()
override suspend fun resendCode(verificationId: String) =
api.resendCode(verificationId).toRequestResult()
}
val verification = rememberPhoneVerificationController(MyVerificationHandler(api))
PhoneNumberField(
state = phoneState,
onValueChange = {},
verificationController = verification,
)
Button(
enabled = phoneState.value.isValid,
onClick = { scope.launch { verification.requestCode(phoneState.value) } },
) { Text("Send code") }
when (val state = verification.state) {
is PhoneVerificationState.CodeSent -> OtpEntry(onSubmit = { scope.launch { verification.submitCode(it) } })
is PhoneVerificationState.Verified -> Text("Verified: ${state.e164Number}")
is PhoneVerificationState.Failed -> Text(state.message.resolve())
else -> Unit
}Editing the phone number after a successful verification resets the flow to Idle automatically — a
form can never submit "verified" for a number the user has since changed.
CountryPickerDefaults.config(
allowedCountryCodes = setOf("US", "CA", "GB", "KE"), // null (default) = every country
excludedCountryCodes = setOf("KP", "IR"), // exclusion always wins
showRegionFilters = true,
)An empty allowedCountryCodes set is a real, deliberate configuration — it allows nothing, and the
sheet shows its own "no countries available" state rather than silently falling back to everything.
CountryPickerDefaults.config(
suggestedCountryCodes = listOf("US", "GB", "KE"), // your call — the library assumes nothing
)
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
recentCountryStore = rememberDefaultRecentCountryStore(), // omit to persist nothing
)Selected, Recent and Suggested are deduplicated against each other and against "All countries" — a selected Germany never also shows up under Suggested.
var markets by rememberSaveable { mutableStateOf(emptySet<Country>()) }
MultiCountrySelector(
selectedCountries = markets,
onSelectionConfirmed = { markets = it }, // fires only when the user taps Confirm
config = CountryPickerDefaults.multiSelectConfig(
minimumSelectionCount = 1,
maximumSelectionCount = 5,
),
)Ticking rows edits a pending selection inside the sheet; Cancel and dismiss discard it, so
selectedCountries never changes except through onSelectionConfirmed.
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
// Android: SIM → network → locale. iOS: the Region setting. No location permission either way.
detector = rememberDefaultCountryDetector(),
detectionBehavior = CountryDetectionBehavior.ShowBadge,
)Detection never overrides a selection the user already made. ShowBadge applies the guess and labels
it ("From your SIM card · tap to change"); AskFirst surfaces it as a suggestion the user must accept;
Silent applies it with no explanation.
Everything visual is one CountryPickerStyle. Pick a preset, give it your brand color, refine it with
copy, and set it once:
val style = CountryPickerStyles.signature(accent = Color(0xFF0F766E)) // or material(), cupertino(), minimal()
CountryPickerTheme(
style.copy(
layout = style.layout.copy(
flagStyle = CountryFlagStyle.Circle, // Tile, Circle, Rounded, Plain, Hidden
flagSource = CountryFlagSource.FlagCdn(
shape = FlagImageShape.OriginalSameHeight, // Waving, OriginalSameWidth, OriginalSameHeight
format = FlagImageFormat.Svg, // Png, WebP, Jpeg, Svg
),
listStyle = CountryListStyle.Cards, // InsetGrouped, Plain, Cards
presentation = PickerPresentation.Adaptive, // sheet on phones, dialog on tablets
),
),
) {
CountrySelector(selectedCountry = country, onCountrySelected = { country = it })
PhoneNumberField(onValueChange = { phone = it })
}Presets follow your MaterialTheme's light or dark mode and the system's reduced-motion setting.
CountryFlagSource.Emoji keeps everything offline. The sample app's Showcase tab lets you try
every option live. See Theming.
The original phone-number component. Still fully supported — it now runs on the Country Picker
foundation internally (ranked search, the full 236-country dataset, AsYouTypeFormatter-based
grouping), but its public API is unchanged.
PhoneNumberInput(
onValueChange = { phone ->
// phone.formattedPhone → "+254 724 154 958"
// phone.phoneNumber → "+254724154958" (E.164)
// phone.country → SelectedCountry(name, code, dialCode, flag)
// phone.isValid → true / false
}
)Hoist PhoneState when you need to read state or drive the field from outside the composable — for example to clear it after form submission, or to validate on button tap.
val phoneState = rememberPhoneState()
PhoneNumberInput(
state = phoneState,
onValueChange = { phone -> ... }
)
Button(onClick = {
if (phoneState.isValid) submit(phoneState.toPhone())
else phoneState.clearPhone()
}) {
Text("Submit")
}// Default: full-screen bottom sheet
PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(
countryPickerStyle = CountryPickerStyle.BottomSheet
)
)
// Compact inline dropdown (better for tablets / landscape)
PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(
countryPickerStyle = CountryPickerStyle.Dropdown
)
)var isError by remember { mutableStateOf(false) }
PhoneNumberInput(
isError = isError,
errorMessage = "Please enter a valid phone number",
onValueChange = { phone ->
isError = !phone.isValid && phone.phoneNumber.isNotEmpty()
}
)PhoneNumberInput(
value = "+254724154958", // pre-fill in E.164 format; country is auto-detected
setCountry = "KE", // or force a specific country (overrides auto-detection)
)PhoneNumberInput(
// Show only these countries
countriesToShow = listOf("US", "GB", "KE", "FR", "AU"),
// Or hide specific ones
countriesExclude = listOf("KP", "IR"),
// Pin frequently-used countries to the top of the picker
pinnedCountries = listOf("US", "GB", "KE"),
)PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(showClearButton = true)
)PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(autoDetectCountry = true)
// Android: SIM → network → configuration locale → default locale → US
// iOS: Region setting → US
)Input is capped at the correct digit count for the selected country by default. Disable it if needed:
PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(enforceMaxLength = false)
)PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(
defaultCountryListStyle = CountryListStyle.Grid // or CountryListStyle.List
)
)PhoneNumberInput(
onDone = {
// Called only when isValid == true and the user taps Done
submitForm()
}
)PhoneNumberInput(
colors = CCPDefaults.colors(
containerColor = Color.White,
borderColor = Color.Gray,
errorBorderColor = Color.Red,
errorColor = Color.Red,
cursorColor = Color.Black,
inputTextColor = Color.DarkGray,
phoneHintColor = Color.LightGray,
)
)PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(
phoneInputShape = RoundedCornerShape(8.dp),
borderWidth = 1.dp,
showCountryFlag = true,
showHeader = true,
showCountriesHeaderDivider = true,
readOnly = false,
)
)| Parameter | Type | Default | Description |
|---|---|---|---|
modifier |
Modifier |
Modifier |
Applied to the outer Column |
state |
PhoneState |
rememberPhoneState() |
Hoistable state holder |
phoneHint |
String |
"Enter phone" |
Placeholder text |
onValueChange |
(Phone) -> Unit |
{} |
Called on every change |
onDone |
() -> Unit |
{} |
Called on IME Done (only when valid) |
value |
String |
"" |
Initial phone number (E.164 or local) |
setCountry |
String? |
null |
ISO code or name to preselect |
countriesToShow |
List<String> |
emptyList() |
Whitelist of ISO codes |
countriesExclude |
List<String> |
emptyList() |
Blacklist of ISO codes |
pinnedCountries |
List<String> |
emptyList() |
ISO codes pinned to top of picker |
isError |
Boolean |
false |
Show error border and message |
errorMessage |
String? |
null |
Text shown below field when isError
|
colors |
CCPColors |
CCPDefaults.colors() |
Color configuration |
ccpConfig |
CCPConfig |
CCPDefaults.defaultConfig() |
Behavior and UI configuration |
| Member | Type | Description |
|---|---|---|
activeCountry |
Country? |
Currently selected country |
phoneNumber |
String |
Raw digit string |
formattedPhone |
String |
International format e.g. +254 724 154 958
|
unformattedPhone |
String |
E.164 format e.g. +254724154958
|
isValid |
Boolean |
Whether the number is valid for the country |
selectCountry(Country) |
fun |
Set active country and reformat |
setCountryByCode(String) |
fun |
Set country by ISO code |
updatePhoneNumber(TextFieldValue) |
fun |
Update field and reformat |
parseAndSet(String) |
fun |
Parse E.164 string, auto-detect country |
clearPhone() |
fun |
Reset field and all derived state |
toPhone() |
fun |
Snapshot current state as Phone
|
data class Phone(
val formattedPhone: String, // e.g. "+254 724 154 958"
val phoneNumber: String, // E.164 e.g. "+254724154958"
val country: SelectedCountry?, // name, code, dialCode, flag
val isValid: Boolean
)| Property | Type | Default | Description |
|---|---|---|---|
autoDetectCountry |
Boolean |
false |
Detect country from SIM / locale |
countryPickerStyle |
CountryPickerStyle |
BottomSheet |
BottomSheet or Dropdown
|
defaultCountryListStyle |
CountryListStyle |
List |
List or Grid
|
showClearButton |
Boolean |
false |
Show × button inside input |
enforceMaxLength |
Boolean |
true |
Cap digits at country's max |
readOnly |
Boolean |
false |
Disable input and country selector |
showCountryFlag |
Boolean |
true |
Flag emoji in the selector button |
showHeader |
Boolean |
true |
Letter headers in country list |
showCountriesHeaderDivider |
Boolean |
true |
Divider next to letter headers |
showFlagCountryItem |
Boolean |
true |
Flag in each country row |
showDialCodeCountryItem |
Boolean |
true |
Dial code in each country row |
borderWidth |
Dp |
0.dp |
Input field border thickness |
phoneInputShape |
Shape |
RoundedCornerShape(16.dp) |
Input container shape |
countriesSheetShape |
Shape |
RoundedCornerShape(top=16.dp) |
Bottom sheet shape |
searchCornerRadius |
Dp |
16.dp |
Search field corner radius |
searchBorderWidth |
Dp |
1.dp |
Search field border thickness |
| Property | Default | Description |
|---|---|---|
containerColor |
colorScheme.background |
Input background |
borderColor |
colorScheme.outline |
Normal border |
errorBorderColor |
colorScheme.error |
Error state border |
errorColor |
colorScheme.error |
Error message text |
cursorColor |
colorScheme.primary |
Text cursor |
inputTextColor |
colorScheme.onSurface |
Entered number text |
phoneHintColor |
colorScheme.onSurfaceVariant |
Placeholder text |
countryCodeTextColor |
colorScheme.onSurface |
Dial code in selector |
countryChevronColor |
colorScheme.onSurface |
Chevron icon |
ccpSheetColor |
— | All bottom sheet / dropdown colors (see CCPSheetColor) |
You do not have to migrate — PhoneNumberInput is fully supported and now runs on the Country Picker
foundation internally, so it already benefits from the bigger dataset, ranked search and progressive
formatting without any change on your part.
Move to the newer API when you want things PhoneNumberInput doesn't expose: multi-selection, region
filters, recents/suggestions, or phone verification. The building blocks map like this:
| Old | New |
|---|---|
PhoneNumberInput(...) |
PhoneNumberField(state = rememberPhoneNumberFieldState(...), ...) |
PhoneState |
PhoneNumberFieldState (nationalDigits, value: PhoneNumberValue, selectCountry, clear) |
Phone |
PhoneNumberValue (e164Number, internationalNumber, isValid, validity) |
Country (com.ezzy.ccp.model) |
Country (com.ezzy.ccp.countrypicker.model) — adds ISO alpha-3, region, aliases |
countriesToShow / countriesExclude
|
CountryPickerConfig.allowedCountryCodes / excludedCountryCodes
|
pinnedCountries |
CountryPickerConfig.suggestedCountryCodes |
CCPConfig.autoDetectCountry |
detector = rememberDefaultCountryDetector() |
CCPColors / CCPConfig shape params |
CountryPickerColors / CountryPickerShapes via CountryPickerDefaults
|
| — (did not exist) |
MultiCountrySelector, region filters, PhoneNumberVerificationHandler
|
A couple of behaviors changed as part of the underlying migration — both are described in the doc
comments on countryList and
PhoneState:
"Czech Republic" → "Czechia", "Turkey" → "Türkiye") — former names remain searchable as
aliases."+1-809" → "+1809"); the hyphenated
form was not valid and broke E.164 normalization.unformattedPhone/E.164 output is empty rather than echoing raw input while a number
is unparseable.https://github.com/user-attachments/assets/f2c7c5b9-85dc-4e4a-9909-4ae57490d561
Copyright (c) 2025 Ezekiel Wachira
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
./gradlew :ccp:verifyRoborazziAndroidHostTest :ccp:iosSimulatorArm64Test :ccp:checkKotlinAbi :ccp:lintThe iOS targets need macOS with Xcode. CI runs those on every pull request (the iOS ones on a macOS runner), plus an assemble of the library, the Android sample app and the iOS sample app, and the Compose UI tests on emulators at API 26 and 34.
Source sets: shared code and the tests that run on both platforms live in commonMain /
commonTest; platform code in androidMain / iosMain; Robolectric and screenshot tests in
androidHostTest; Compose UI tests in androidDeviceTest. Kotlin/Native does not allow commas in
backticked test names, so commonTest names avoid them.
Three of them are worth explaining:
verifyRoborazziAndroidHostTest runs the JVM tests and diffs the screenshot suite against the
goldens in ccp/src/androidHostTest/screenshots. Re-record deliberately with
./gradlew :ccp:recordRoborazziAndroidHostTest and review the image diff.checkKotlinAbi compares the compiled public API of every target against the dumps in
ccp/api/ (android/ccp.api, ccp.klib.api). The module is in Kotlin explicit-API mode, so every
public declaration states its visibility and return type, and any change to the published ABI has
to be an explicit commit. When a change is intended, run ./gradlew :ccp:updateKotlinAbi and
commit the diff — that diff is the API review.lint treats warnings as errors and has no baseline file. The module sits at zero findings; a
baseline would only let the next regression be recorded rather than fixed.ccp/src/nativeInterop/libPhoneNumber-iOS is an unmodified copy of libPhoneNumber-iOS (version in its
VERSION file, Apache-2.0 licence alongside). scripts/build-libphonenumber-ios.sh compiles it per
iOS target with every global symbol renamed by ccp_libphonenumber_namespace.h, and fails if any
symbol escapes the prefix. To update it, copy the new release's libPhoneNumber/ and
libPhoneNumberInternal/ headers and sources over the old ones, update VERSION, and bump
lib-phone in gradle/libs.versions.toml to the libphonenumber release the new metadata was
generated from, so Android and iOS stay on the same data.
The Android artifact ships ccp/src/androidMain/generated/baselineProfiles/baseline-prof.txt, which
consuming apps merge so the picker's code is compiled ahead of time on install. :baselineprofile
records it by driving the sample app through the sheet, search and phone field, filtered to the
library's own classes. Regenerate it after changes to those paths:
./gradlew :ccp:generateBaselineProfile # boots a managed API 34 emulator; no device neededThe same module holds the macrobenchmarks that measure it. To compare builds with and without the profile, run them on a physical device with the file present and removed:
./gradlew :baselineprofile:connectedBenchmarkReleaseAndroidTest \
-Pandroid.testInstrumentationRunnerArguments.androidx.benchmark.enabledRules=MacrobenchmarkRegenerate the baseline profile if the sheet, search or phone field changed since the last release,
and commit it. Then push a v* tag. .github/workflows/release.yml writes the version from the tag into
gradle.properties, re-runs the full verification, publishes to Maven Central and drafts the GitHub
release. It needs MAVEN_CENTRAL_USERNAME, MAVEN_CENTRAL_PASSWORD, SIGNING_KEY and
SIGNING_KEY_PASSWORD as repository secrets.
📖 Documentation: ezekielwachira.github.io/Country-Code-Picker — guides, recipes and the API reference.
A lightweight, fully customizable Compose Multiplatform library for Android and iOS: country selection, country code selection, phone number validation, and real-time formatting based on country-specific rules — one API, written once in common code.
The library ships two layers:
PhoneNumberInput — the original phone-number component. It now
runs on the Country Picker foundation internally, so existing call sites keep working unchanged; see
Migrating from PhoneNumberInput if you want to move to the newer
API.The Signature style, with flagcdn.com flags, on iOS. The same code renders it on Android.
![]() Country sheet |
![]() Phone field |
![]() Multiple selection |
![]() "Did you mean" |
![]() Dark mode |
![]() Fields and pills |
Every option above — presets, accent, density, list style, flag shape, format and frame — is a live control in the sample app's Showcase tab.
CountryPickerStyle (colors, shapes, type, motion, elevation,
layout, haptics) with Signature, Material, Cupertino and Minimal presets, three densities, light and
dark, and a brand accent in one lineCountryPickerPanel inlinecommonMain code via Compose Multiplatform+254… adopts its own countryPhoneNumberVerificationHandler
CountryPickerState / PhoneState to the caller for external control✓ Mobile badge once the number is valid+254 never
renders as 254+
The library is published to Maven Central
as io.github.ezekielwachira:ccp. In a Kotlin Multiplatform module, add it to commonMain:
kotlin {
sourceSets {
commonMain.dependencies {
implementation("io.github.ezekielwachira:ccp:0.3.0")
}
}
}In an Android-only module, as before:
dependencies {
implementation("io.github.ezekielwachira:ccp:0.3.0")
}mavenCentral() is in most projects' repository list already; nothing else to add. Gradle picks the
right artifact per target (ccp-android, ccp-iosarm64, ccp-iossimulatorarm64).
Nothing beyond the Gradle dependency. The phone-number engine (libPhoneNumber-iOS) is compiled into the library's iOS klib, so there is no CocoaPod, Swift package or linker flag to add, and an app that also uses libPhoneNumber-iOS directly links fine — the embedded copy's symbols are prefixed.
Host the shared UI the usual Compose Multiplatform way, from your iOS source set:
fun MainViewController(): UIViewController = ComposeUIViewController {
var country by remember { mutableStateOf<Country?>(null) }
CountrySelector(selectedCountry = country, onCountrySelected = { country = it })
}iosApp/ is a complete example: open iosApp/iosApp.xcodeproj in Xcode and run the
CCP Sample scheme. It builds the shared :sample module — the same demo the Android
:app runs.
0.3.0 is the first release on Maven Central. Earlier versions were published only through JitPack,
under a different coordinate, and are Android-only (JitPack builds on Linux, which cannot produce the
iOS artifacts). To stay on one of those, add the JitPack repository to your root settings.gradle.kts:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}dependencies {
implementation("com.github.EzekielWachira:Country-Code-Picker:0.2.0")
}libphonenumber ships three metadata blobs. The picker only ever reaches PhoneNumberUtil and
AsYouTypeFormatter, which need one of them:
| Blob | Size | Needed |
|---|---|---|
PhoneNumberMetadataProto |
~235 KB | yes |
ShortNumberMetadataProto |
~75 KB | only by ShortNumberInfo — unused here |
PhoneNumberAlternateFormatsProto |
~23 KB | only by PhoneNumberMatcher — unused here |
If your app does not use those APIs either, drop the two unused blobs:
android {
packaging {
resources {
excludes += setOf(
"/com/google/i18n/phonenumbers/data/ShortNumberMetadataProto*",
"/com/google/i18n/phonenumbers/data/PhoneNumberAlternateFormatsProto*",
)
}
}
}The sample app in this repository ships with these exclusions applied, so CI builds and tests the
configuration rather than only documenting it. A build task (verifyPhoneNumberMetadataFootprint)
fails the library's own build if it ever starts using an API that would need them back.
Everything below lives under com.ezzy.ccp.countrypicker — the country model, search, state, theme
and UI are all reusable independently of phone numbers. A sample screen reproducing the flow below is
in YourDetailsSampleScreen,
and every state described here has a matching @Preview in
CountryPickerPreviews.kt.
var country by rememberSaveable { mutableStateOf<Country?>(null) }
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
label = UiText.of("Country of residence"),
)CountrySelector is fully controlled: selectedCountry is the source of truth, and the component never
mutates it — a selection only ever arrives through onCountrySelected, carrying the complete Country
(ISO alpha-2/3, dial code, region, flag), never just a name or a code.
Same sheet, same behavior, smaller footprint — pick with variant:
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
variant = CountrySelectorVariant.Compact, // 🇩🇪 Germany ˅
label = null,
)
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
variant = CountrySelectorVariant.FlagOnly, // 🇩🇪 ˅
label = null,
)The flag-only variant has no visible text, so it carries its own content description automatically —
"Selected country: Germany. Double tap to change." — no extra wiring needed.
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
variant = CountrySelectorVariant.DialCode, // 🇰🇪 +254 ˅
label = null,
config = CountryPickerDefaults.phoneConfig(),
)In practice you won't call this directly — PhoneNumberField already embeds
it next to the number input.
val phoneState = rememberPhoneNumberFieldState(initialCountry = kenya)
PhoneNumberField(
state = phoneState,
onValueChange = { value: PhoneNumberValue ->
value.e164Number // "+254712345678", or null while unparseable
value.internationalNumber // "+254 712 345678"
value.isValid // true only for a real, dialable number
},
)PhoneNumberValue.e164Number comes from libphonenumber, not from concatenating a dial code onto typed
digits — that concatenation is wrong for any region with a national trunk prefix (a UK mobile typed as
07400 123456 is +447400123456, not +4407400123456). Never rebuild it by hand.
Changing the selected country keeps the digits the user already typed, reformats them for the new region, and revalidates — a number valid in one country is never carried over as still-valid in another.
when (phoneState.value.validity) {
PhoneNumberValidity.Empty -> Unit // nothing typed; show nothing
PhoneNumberValidity.Incomplete -> Unit // still typing; show nothing
PhoneNumberValidity.Valid -> submit()
else -> showError(PhoneNumberValidator.errorMessage(phoneState.value))
}PhoneNumberField already shows/hides its own error text this way; reach for PhoneNumberValidator
directly only when you need the result before the user submits.
The library ships no verification backend on purpose — implement the one contract against your own SMS/Firebase/whatever provider:
class MyVerificationHandler(private val api: MyAuthApi) : PhoneNumberVerificationHandler {
override suspend fun requestVerification(phoneNumber: PhoneNumberValue) =
api.sendCode(phoneNumber.e164Number!!).toRequestResult()
override suspend fun verifyCode(verificationId: String, code: String) =
api.checkCode(verificationId, code).toVerificationResult()
override suspend fun resendCode(verificationId: String) =
api.resendCode(verificationId).toRequestResult()
}
val verification = rememberPhoneVerificationController(MyVerificationHandler(api))
PhoneNumberField(
state = phoneState,
onValueChange = {},
verificationController = verification,
)
Button(
enabled = phoneState.value.isValid,
onClick = { scope.launch { verification.requestCode(phoneState.value) } },
) { Text("Send code") }
when (val state = verification.state) {
is PhoneVerificationState.CodeSent -> OtpEntry(onSubmit = { scope.launch { verification.submitCode(it) } })
is PhoneVerificationState.Verified -> Text("Verified: ${state.e164Number}")
is PhoneVerificationState.Failed -> Text(state.message.resolve())
else -> Unit
}Editing the phone number after a successful verification resets the flow to Idle automatically — a
form can never submit "verified" for a number the user has since changed.
CountryPickerDefaults.config(
allowedCountryCodes = setOf("US", "CA", "GB", "KE"), // null (default) = every country
excludedCountryCodes = setOf("KP", "IR"), // exclusion always wins
showRegionFilters = true,
)An empty allowedCountryCodes set is a real, deliberate configuration — it allows nothing, and the
sheet shows its own "no countries available" state rather than silently falling back to everything.
CountryPickerDefaults.config(
suggestedCountryCodes = listOf("US", "GB", "KE"), // your call — the library assumes nothing
)
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
recentCountryStore = rememberDefaultRecentCountryStore(), // omit to persist nothing
)Selected, Recent and Suggested are deduplicated against each other and against "All countries" — a selected Germany never also shows up under Suggested.
var markets by rememberSaveable { mutableStateOf(emptySet<Country>()) }
MultiCountrySelector(
selectedCountries = markets,
onSelectionConfirmed = { markets = it }, // fires only when the user taps Confirm
config = CountryPickerDefaults.multiSelectConfig(
minimumSelectionCount = 1,
maximumSelectionCount = 5,
),
)Ticking rows edits a pending selection inside the sheet; Cancel and dismiss discard it, so
selectedCountries never changes except through onSelectionConfirmed.
CountrySelector(
selectedCountry = country,
onCountrySelected = { country = it },
// Android: SIM → network → locale. iOS: the Region setting. No location permission either way.
detector = rememberDefaultCountryDetector(),
detectionBehavior = CountryDetectionBehavior.ShowBadge,
)Detection never overrides a selection the user already made. ShowBadge applies the guess and labels
it ("From your SIM card · tap to change"); AskFirst surfaces it as a suggestion the user must accept;
Silent applies it with no explanation.
Everything visual is one CountryPickerStyle. Pick a preset, give it your brand color, refine it with
copy, and set it once:
val style = CountryPickerStyles.signature(accent = Color(0xFF0F766E)) // or material(), cupertino(), minimal()
CountryPickerTheme(
style.copy(
layout = style.layout.copy(
flagStyle = CountryFlagStyle.Circle, // Tile, Circle, Rounded, Plain, Hidden
flagSource = CountryFlagSource.FlagCdn(
shape = FlagImageShape.OriginalSameHeight, // Waving, OriginalSameWidth, OriginalSameHeight
format = FlagImageFormat.Svg, // Png, WebP, Jpeg, Svg
),
listStyle = CountryListStyle.Cards, // InsetGrouped, Plain, Cards
presentation = PickerPresentation.Adaptive, // sheet on phones, dialog on tablets
),
),
) {
CountrySelector(selectedCountry = country, onCountrySelected = { country = it })
PhoneNumberField(onValueChange = { phone = it })
}Presets follow your MaterialTheme's light or dark mode and the system's reduced-motion setting.
CountryFlagSource.Emoji keeps everything offline. The sample app's Showcase tab lets you try
every option live. See Theming.
The original phone-number component. Still fully supported — it now runs on the Country Picker
foundation internally (ranked search, the full 236-country dataset, AsYouTypeFormatter-based
grouping), but its public API is unchanged.
PhoneNumberInput(
onValueChange = { phone ->
// phone.formattedPhone → "+254 724 154 958"
// phone.phoneNumber → "+254724154958" (E.164)
// phone.country → SelectedCountry(name, code, dialCode, flag)
// phone.isValid → true / false
}
)Hoist PhoneState when you need to read state or drive the field from outside the composable — for example to clear it after form submission, or to validate on button tap.
val phoneState = rememberPhoneState()
PhoneNumberInput(
state = phoneState,
onValueChange = { phone -> ... }
)
Button(onClick = {
if (phoneState.isValid) submit(phoneState.toPhone())
else phoneState.clearPhone()
}) {
Text("Submit")
}// Default: full-screen bottom sheet
PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(
countryPickerStyle = CountryPickerStyle.BottomSheet
)
)
// Compact inline dropdown (better for tablets / landscape)
PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(
countryPickerStyle = CountryPickerStyle.Dropdown
)
)var isError by remember { mutableStateOf(false) }
PhoneNumberInput(
isError = isError,
errorMessage = "Please enter a valid phone number",
onValueChange = { phone ->
isError = !phone.isValid && phone.phoneNumber.isNotEmpty()
}
)PhoneNumberInput(
value = "+254724154958", // pre-fill in E.164 format; country is auto-detected
setCountry = "KE", // or force a specific country (overrides auto-detection)
)PhoneNumberInput(
// Show only these countries
countriesToShow = listOf("US", "GB", "KE", "FR", "AU"),
// Or hide specific ones
countriesExclude = listOf("KP", "IR"),
// Pin frequently-used countries to the top of the picker
pinnedCountries = listOf("US", "GB", "KE"),
)PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(showClearButton = true)
)PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(autoDetectCountry = true)
// Android: SIM → network → configuration locale → default locale → US
// iOS: Region setting → US
)Input is capped at the correct digit count for the selected country by default. Disable it if needed:
PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(enforceMaxLength = false)
)PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(
defaultCountryListStyle = CountryListStyle.Grid // or CountryListStyle.List
)
)PhoneNumberInput(
onDone = {
// Called only when isValid == true and the user taps Done
submitForm()
}
)PhoneNumberInput(
colors = CCPDefaults.colors(
containerColor = Color.White,
borderColor = Color.Gray,
errorBorderColor = Color.Red,
errorColor = Color.Red,
cursorColor = Color.Black,
inputTextColor = Color.DarkGray,
phoneHintColor = Color.LightGray,
)
)PhoneNumberInput(
ccpConfig = CCPDefaults.defaultConfig(
phoneInputShape = RoundedCornerShape(8.dp),
borderWidth = 1.dp,
showCountryFlag = true,
showHeader = true,
showCountriesHeaderDivider = true,
readOnly = false,
)
)| Parameter | Type | Default | Description |
|---|---|---|---|
modifier |
Modifier |
Modifier |
Applied to the outer Column |
state |
PhoneState |
rememberPhoneState() |
Hoistable state holder |
phoneHint |
String |
"Enter phone" |
Placeholder text |
onValueChange |
(Phone) -> Unit |
{} |
Called on every change |
onDone |
() -> Unit |
{} |
Called on IME Done (only when valid) |
value |
String |
"" |
Initial phone number (E.164 or local) |
setCountry |
String? |
null |
ISO code or name to preselect |
countriesToShow |
List<String> |
emptyList() |
Whitelist of ISO codes |
countriesExclude |
List<String> |
emptyList() |
Blacklist of ISO codes |
pinnedCountries |
List<String> |
emptyList() |
ISO codes pinned to top of picker |
isError |
Boolean |
false |
Show error border and message |
errorMessage |
String? |
null |
Text shown below field when isError
|
colors |
CCPColors |
CCPDefaults.colors() |
Color configuration |
ccpConfig |
CCPConfig |
CCPDefaults.defaultConfig() |
Behavior and UI configuration |
| Member | Type | Description |
|---|---|---|
activeCountry |
Country? |
Currently selected country |
phoneNumber |
String |
Raw digit string |
formattedPhone |
String |
International format e.g. +254 724 154 958
|
unformattedPhone |
String |
E.164 format e.g. +254724154958
|
isValid |
Boolean |
Whether the number is valid for the country |
selectCountry(Country) |
fun |
Set active country and reformat |
setCountryByCode(String) |
fun |
Set country by ISO code |
updatePhoneNumber(TextFieldValue) |
fun |
Update field and reformat |
parseAndSet(String) |
fun |
Parse E.164 string, auto-detect country |
clearPhone() |
fun |
Reset field and all derived state |
toPhone() |
fun |
Snapshot current state as Phone
|
data class Phone(
val formattedPhone: String, // e.g. "+254 724 154 958"
val phoneNumber: String, // E.164 e.g. "+254724154958"
val country: SelectedCountry?, // name, code, dialCode, flag
val isValid: Boolean
)| Property | Type | Default | Description |
|---|---|---|---|
autoDetectCountry |
Boolean |
false |
Detect country from SIM / locale |
countryPickerStyle |
CountryPickerStyle |
BottomSheet |
BottomSheet or Dropdown
|
defaultCountryListStyle |
CountryListStyle |
List |
List or Grid
|
showClearButton |
Boolean |
false |
Show × button inside input |
enforceMaxLength |
Boolean |
true |
Cap digits at country's max |
readOnly |
Boolean |
false |
Disable input and country selector |
showCountryFlag |
Boolean |
true |
Flag emoji in the selector button |
showHeader |
Boolean |
true |
Letter headers in country list |
showCountriesHeaderDivider |
Boolean |
true |
Divider next to letter headers |
showFlagCountryItem |
Boolean |
true |
Flag in each country row |
showDialCodeCountryItem |
Boolean |
true |
Dial code in each country row |
borderWidth |
Dp |
0.dp |
Input field border thickness |
phoneInputShape |
Shape |
RoundedCornerShape(16.dp) |
Input container shape |
countriesSheetShape |
Shape |
RoundedCornerShape(top=16.dp) |
Bottom sheet shape |
searchCornerRadius |
Dp |
16.dp |
Search field corner radius |
searchBorderWidth |
Dp |
1.dp |
Search field border thickness |
| Property | Default | Description |
|---|---|---|
containerColor |
colorScheme.background |
Input background |
borderColor |
colorScheme.outline |
Normal border |
errorBorderColor |
colorScheme.error |
Error state border |
errorColor |
colorScheme.error |
Error message text |
cursorColor |
colorScheme.primary |
Text cursor |
inputTextColor |
colorScheme.onSurface |
Entered number text |
phoneHintColor |
colorScheme.onSurfaceVariant |
Placeholder text |
countryCodeTextColor |
colorScheme.onSurface |
Dial code in selector |
countryChevronColor |
colorScheme.onSurface |
Chevron icon |
ccpSheetColor |
— | All bottom sheet / dropdown colors (see CCPSheetColor) |
You do not have to migrate — PhoneNumberInput is fully supported and now runs on the Country Picker
foundation internally, so it already benefits from the bigger dataset, ranked search and progressive
formatting without any change on your part.
Move to the newer API when you want things PhoneNumberInput doesn't expose: multi-selection, region
filters, recents/suggestions, or phone verification. The building blocks map like this:
| Old | New |
|---|---|
PhoneNumberInput(...) |
PhoneNumberField(state = rememberPhoneNumberFieldState(...), ...) |
PhoneState |
PhoneNumberFieldState (nationalDigits, value: PhoneNumberValue, selectCountry, clear) |
Phone |
PhoneNumberValue (e164Number, internationalNumber, isValid, validity) |
Country (com.ezzy.ccp.model) |
Country (com.ezzy.ccp.countrypicker.model) — adds ISO alpha-3, region, aliases |
countriesToShow / countriesExclude
|
CountryPickerConfig.allowedCountryCodes / excludedCountryCodes
|
pinnedCountries |
CountryPickerConfig.suggestedCountryCodes |
CCPConfig.autoDetectCountry |
detector = rememberDefaultCountryDetector() |
CCPColors / CCPConfig shape params |
CountryPickerColors / CountryPickerShapes via CountryPickerDefaults
|
| — (did not exist) |
MultiCountrySelector, region filters, PhoneNumberVerificationHandler
|
A couple of behaviors changed as part of the underlying migration — both are described in the doc
comments on countryList and
PhoneState:
"Czech Republic" → "Czechia", "Turkey" → "Türkiye") — former names remain searchable as
aliases."+1-809" → "+1809"); the hyphenated
form was not valid and broke E.164 normalization.unformattedPhone/E.164 output is empty rather than echoing raw input while a number
is unparseable.https://github.com/user-attachments/assets/f2c7c5b9-85dc-4e4a-9909-4ae57490d561
Copyright (c) 2025 Ezekiel Wachira
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
./gradlew :ccp:verifyRoborazziAndroidHostTest :ccp:iosSimulatorArm64Test :ccp:checkKotlinAbi :ccp:lintThe iOS targets need macOS with Xcode. CI runs those on every pull request (the iOS ones on a macOS runner), plus an assemble of the library, the Android sample app and the iOS sample app, and the Compose UI tests on emulators at API 26 and 34.
Source sets: shared code and the tests that run on both platforms live in commonMain /
commonTest; platform code in androidMain / iosMain; Robolectric and screenshot tests in
androidHostTest; Compose UI tests in androidDeviceTest. Kotlin/Native does not allow commas in
backticked test names, so commonTest names avoid them.
Three of them are worth explaining:
verifyRoborazziAndroidHostTest runs the JVM tests and diffs the screenshot suite against the
goldens in ccp/src/androidHostTest/screenshots. Re-record deliberately with
./gradlew :ccp:recordRoborazziAndroidHostTest and review the image diff.checkKotlinAbi compares the compiled public API of every target against the dumps in
ccp/api/ (android/ccp.api, ccp.klib.api). The module is in Kotlin explicit-API mode, so every
public declaration states its visibility and return type, and any change to the published ABI has
to be an explicit commit. When a change is intended, run ./gradlew :ccp:updateKotlinAbi and
commit the diff — that diff is the API review.lint treats warnings as errors and has no baseline file. The module sits at zero findings; a
baseline would only let the next regression be recorded rather than fixed.ccp/src/nativeInterop/libPhoneNumber-iOS is an unmodified copy of libPhoneNumber-iOS (version in its
VERSION file, Apache-2.0 licence alongside). scripts/build-libphonenumber-ios.sh compiles it per
iOS target with every global symbol renamed by ccp_libphonenumber_namespace.h, and fails if any
symbol escapes the prefix. To update it, copy the new release's libPhoneNumber/ and
libPhoneNumberInternal/ headers and sources over the old ones, update VERSION, and bump
lib-phone in gradle/libs.versions.toml to the libphonenumber release the new metadata was
generated from, so Android and iOS stay on the same data.
The Android artifact ships ccp/src/androidMain/generated/baselineProfiles/baseline-prof.txt, which
consuming apps merge so the picker's code is compiled ahead of time on install. :baselineprofile
records it by driving the sample app through the sheet, search and phone field, filtered to the
library's own classes. Regenerate it after changes to those paths:
./gradlew :ccp:generateBaselineProfile # boots a managed API 34 emulator; no device neededThe same module holds the macrobenchmarks that measure it. To compare builds with and without the profile, run them on a physical device with the file present and removed:
./gradlew :baselineprofile:connectedBenchmarkReleaseAndroidTest \
-Pandroid.testInstrumentationRunnerArguments.androidx.benchmark.enabledRules=MacrobenchmarkRegenerate the baseline profile if the sheet, search or phone field changed since the last release,
and commit it. Then push a v* tag. .github/workflows/release.yml writes the version from the tag into
gradle.properties, re-runs the full verification, publishes to Maven Central and drafts the GitHub
release. It needs MAVEN_CENTRAL_USERNAME, MAVEN_CENTRAL_PASSWORD, SIGNING_KEY and
SIGNING_KEY_PASSWORD as repository secrets.