Kompose Country Code Picker

The isPhoneNumberValid() API remains unchanged in signature, but the underlying validation engine depends on the target platform:

• Android / JVM: Uses Google's libphonenumber.
• iOS / JS / WasmJS: Uses built-in per-country digit-length rules.

When using the library, be aware of the following platform-specific behaviors:

• Keyboard Navigation: On Desktop and Web platforms, the country selection dialog supports Arrow keys, Enter, and Escape.
• Responsive Dialog: The country selection dialog is responsive. It appears as a full-screen view on compact screens (width < 600dp) and as a popup on expanded screens.
• Validation Engines: Android and JVM provide high-accuracy validation via Google's libphonenumber. iOS, JS, and WasmJS use built-in digit-length rules which cover most standard use cases.

For standalone Android projects, add the dependency directly to your app's build.gradle.kts file. Ensure mavenCentral() is present in your repositories.

Using Kotlin DSL

dependencies {
    implementation("io.github.joelkanyi:komposecountrycodepicker:<latest-version>")
}

Using Gradle Version Catalog

1. Add the version and library to libs.versions.toml:

[versions]
komposecountrycodepicker = "<latest-version>"

[libraries]
komposecountrycodepicker = { module = "io.github.joelkanyi:komposecountrycodepicker", version.ref = "komposecountrycodepicker" }

2. Apply the dependency in your build.gradle.kts:

dependencies {
    implementation(libs.komposecountrycodepicker)
}

You can run the provided sample applications located in the sample/ directory using the following commands:

• Android: ./gradlew :sample:android:installDebug
• Desktop (JVM): ./gradlew :sample:desktop:run
• Web (JS): ./gradlew :sample:web-js:jsBrowserDevelopmentRun
• Web (WasmJS): ./gradlew :sample:web-wasm:wasmJsBrowserDevelopmentRun
• iOS: Open sample/iosApp/iosApp.xcodeproj in Xcode and run on a simulator or device.

# Android
./gradlew :sample:android:installDebug

# Desktop (JVM)
./gradlew :sample:desktop:run

# Web (JS)
./gradlew :sample:web-js:jsBrowserDevelopmentRun

# Web (WasmJS)
./gradlew :sample:web-wasm:wasmJsBrowserDevelopmentRun

By default, textStyle applies to both the phone number input and the country code. To apply different styles to each, use the countryCodeTextStyle parameter for the country code specifically.

KomposeCountryCodePicker(
    modifier = Modifier.fillMaxWidth(),
    text = phoneNumber,
    onValueChange = { phoneNumber = it },
    state = state,
    textStyle = MaterialTheme.typography.bodyLarge, // phone number input
    countryCodeTextStyle = MaterialTheme.typography.labelMedium.copy(
        fontWeight = FontWeight.Medium,
        color = MaterialTheme.colorScheme.primary,
    ), // country code only
)

The library automatically detects the user's country based on platform-specific methods (e.g., Locale.getDefault().country on Android/JVM, NSLocale on iOS, or navigator.language on Web).

To bypass auto-detection and set a specific starting country, pass the defaultCountryCode parameter to rememberKomposeCountryCodePickerState().

// Example of overriding auto-detection
val state = rememberKomposeCountryCodePickerState(defaultCountryCode = "US")

If you are upgrading from the Android-only version of Kompose Country Code Picker to the Compose Multiplatform version, you must move the dependency from your Android app/build.gradle.kts to your KMP module's commonMain source set. The Maven coordinates remain identical.

// In your KMP module's build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.joelkanyi:komposecountrycodepicker:x.y.z")
        }
    }
}

The primary usage pattern is to use KomposeCountryCodePicker as a complete input component. It provides an OutlinedTextField with an integrated country code picker as the leading icon. It follows the standard Compose controlled-text pattern using text and onValueChange.

var phoneNumber by rememberSaveable { mutableStateOf("") }
val state = rememberKomposeCountryCodePickerState(
    showCountryCode = true,
    showCountryFlag = true,
)

KomposeCountryCodePicker(
    modifier = Modifier.fillMaxWidth(),
    text = phoneNumber,
    onValueChange = { phoneNumber = it },
    placeholder = { 
        Text(text = "Phone Number") 
    },
    shape = MaterialTheme.shapes.medium,
    colors = TextFieldDefaults.colors(
        unfocusedContainerColor = Color.Transparent,
        focusedContainerColor = Color.Transparent,
    ),
    state = state,
)

If you have a custom text field and only want to use the library's searchable country list and flag assets, use the CountrySelectionDialog composable independently.

To update the state when a user selects a country, call state.setCode(country.code). You can then access the selected country's details via state.selectedCountry (providing flag, name, and phoneNoCode).

CountrySelectionDialog(
    countryList = state.countryList,
    containerColor = MaterialTheme.colorScheme.background,
    contentColor = MaterialTheme.colorScheme.onBackground,
    onDismissRequest = { /* handle dismiss */ },
    onSelect = { country ->
        state.setCode(country.code) // updates state.selectedCountry
    },
)

To display only the country selector without an attached text field (useful for embedding in custom layouts or as a leadingIcon), set showOnlyCountryCodePicker = true.

val state = rememberKomposeCountryCodePickerState()

KomposeCountryCodePicker(
    modifier = Modifier,
    showOnlyCountryCodePicker = true,
    text = phoneNumber,
    state = state,
)