kmp-country-selector

KO | EN

gitlite — search

#javascript #hacktoberfest #react #go #android #linux #docker #java #kubernetes #vue #pytorch #mcp #openai #open-source

kmp-country-selector

(★ 15)

Kotlin Multiplatform Country Code and Dial Code Picker with Flag Support, Search and Localization

kmp-country-selector Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Build iOS](https://github.com/WannaverseOfficial/kmp-country-selector/actions/workflows/build-mac.yaml/badge.svg)](https://github.com/WannaverseOfficial/kmp-country-selector/actions)
[![Build Linux](https://github.com/WannaverseOfficial/kmp-country-selector/actions/workflows/build-linux.yaml/badge.svg)](https://github.com/WannaverseOfficial/kmp-country-selector/actions)

# 🚩 Country Selector
A Kotlin Multiplatform **Country Code** and **Dial Code** Picker with flag support and search functionality.
This library provides a customizable dropdown component that enables users to:

* Search and select any country
* Retrieve the country name, ISO country code (GB, US, FR etc.)
* Get the country dial code (+44, +1, +33 etc.)
* Display the country flag and retrieve usable a flag resource
* View countries in their native device language e.g. instead of "Germany", a German user will see "Deutschland"

## 🧩 Features
* 🌍 Full list of countries and dial codes
* 🔍 Search by name or dial code
* 🎏 Native flag support
* 📦 Lightweight & efficient
* ♻️ Kotlin Multiplatform compatible
* 🌐 Built-in localization support

## ✅ Supported Platform

| Platform | Supported |
|:---------|:----------|
| Android  | ✔️        |
| iOS      | ✔️        |
| Desktop  | ✔️        |
| Web      | ❌️        |

## 🚀 Installation
See the releases section of this repository for the latest version.

To your `build.gradle` under `commonMain.dependencies` add:
```kotlin
implementation "com.wannaverse:countryselector:<version>"
```

**Important** this library uses native code to handle translations. You will need the additional dependencies depending on the targets you are building for:

**Android** under `androidMain.dependencies`:
implementation("com.wannaverse:countryselector-android:<version>")

**iOS (ARM)** under `iosMain.dependencies`:
implementation("com.wannaverse:countryselector-iosarm64:<version>")

**iOS x64** under `iosMain.dependencies`:
implementation("com.wannaverse:countryselector-iosx64:<version>")

**jvm**:
implementation("com.wannaverse:countryselector-jvm:<version>")

## Usage

[KDocs](https://wannaverseofficial.github.io/kmp-country-selector/)

Below is a sample code that you may use.
Be aware: The `Box` is required if you are using any sort of scroll behavior with your screen. This is because this `CountryPickerIcon` uses a [`LazyColumn`](https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/package-summary?_gl=1*nq0b0g*_up*MQ..*_ga*MzU2NTQxNzE1LjE3NDU2MTE0ODg.*_ga_6HH9YJMN9M*MTc0NTYxMTQ4OC4xLjAuMTc0NTYxMTQ4OC4wLjAuNjU4NTM2NzAx#LazyColumn(androidx.compose.ui.Modifier,androidx.compose.foundation.lazy.LazyListState,androidx.compose.foundation.layout.PaddingValues,kotlin.Boolean,androidx.compose.foundation.layout.Arrangement.Vertical,androidx.compose.ui.Alignment.Horizontal,androidx.compose.foundation.gestures.FlingBehavior,kotlin.Boolean,kotlin.Function1)) for it's scrollable functionality.
```kotlin
var selectedCountry by remember { mutableStateOf(Countries.US) }

Box(
    modifier = Modifier.fillMaxSize(),
    contentAlignment = Alignment.Center
) {
    Box(
        modifier = Modifier.height(50.dp)
            .border(
                width = 1.dp,
                color = MaterialTheme.colorScheme.outline,
                shape = MaterialTheme.shapes.medium
            )
            .padding(8.dp),
        contentAlignment = Alignment.Center
    ) {
        CountrySelector(
            country = selectedCountry,
            onSelection = { selectedCountry = it }
        )
    }
}
```

To change the language of the country picker manually, before creating the `CountryPickerIcon` set:
```kotlin
Countries.languageTag = "es" // as long as it's a IETF language tag
```

### Adding UI Translations

Country names are translated automatically by the device OS. The picker's UI strings (search bar label, placeholder, empty state message) use Compose Multiplatform string resources and can be translated by contributing a locale file.

To add a translation, create a new file at:
```
countryselector/src/commonMain/composeResources/values-<language-code>/strings.xml
```

For example, for French (`fr`):
```
countryselector/src/commonMain/composeResources/values-fr/strings.xml
```

The file must define all 5 keys:
```xml
<resources>
    <string name="no_countries_found"></string>
    <string name="search_label"></string>
    <string name="search_placeholder"></string>
    <string name="search_content_description"></string>
    <string name="open_picker_content_description"></string>
</resources>
```

The correct string will be picked up automatically based on the device locale — no code changes needed. Use standard [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag) for the folder suffix (e.g. `values-de`, `values-fr`, `values-zh`, `values-hi`).

You can further customize the look and feel of the picker so that it's exactly how you want it:
```kotlin
Box(
    modifier = Modifier.fillMaxSize(),
    contentAlignment = Alignment.Center
) {
    Box(
        modifier = Modifier
            .height(50.dp)
            .border(
                width = 1.dp,
                color = MaterialTheme.colorScheme.outline,
                shape = MaterialTheme.shapes.medium
            )
            .padding(8.dp),
        contentAlignment = Alignment.Center
    ) {
        CountrySelector(
            country = selectedCountry,
            onSelection = { selectedCountry = it },
            pickerRowContent = { country ->
                Row(
                    modifier = Modifier,
                    verticalAlignment = Alignment.CenterVertically
                ) {
                    Image(
                        painter = painterResource(
                            resource = country.flagImageResource,
                            ),
                        contentDescription = country.countryName,
                        modifier = Modifier
                            .size(24.dp)
                            .clip(CircleShape)
                    )

Spacer(Modifier.width(8.dp))

Text(country.countryName)

Spacer(Modifier.weight(1f))

Text(country.internationalDialCode)
                } },
            searchBarContent = { searchQuery, onQueryChange, hasError ->
                TextField(
                    value = searchQuery,
                    onValueChange = onQueryChange,
                    modifier = Modifier
                        .fillMaxWidth()
                        .padding(10.dp),
                    label = { Text("Search Countries") },
                    trailingIcon = {
                        if (hasError) {
                            Icon(Icons.Default.Error, contentDescription = "No results found")
                        } },
                    isError = hasError,
                    placeholder = { Text("Search by country name or code") }
                )
            }
        )
    }
}
```
## Screenshots
### Android
|              Light Theme               |              Dark Theme               |
|:--------------------------------------:|:-------------------------------------:|
| ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/Android_light_closed.png) | ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/Android_dark_closed.png) |
| ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/Android_light_drawer.png) | ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/Android_dark_search.png) |
| ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/Android_light_search.png) | ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/Android_dark_drawer.png) |

### iOS
|              Light Theme              |              Dark Theme              |
|:-------------------------------------:|:------------------------------------:|
| ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/IPhone_light_closed.png) | ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/IPhone_dark_closed.png) |
| ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/IPhone_light_drawer.png) | ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/IPhone_dark_drawer.png) |
| ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/IPhone_light_search.png) | ![](https://raw.githubusercontent.com/WannaverseOfficial/kmp-country-selector/main/assets/IPhone_dark_search.png) |

## 📄 License
MIT LICENSE. See [LICENSE](./LICENSE) for details.

## 🙌 Contributing
Pull requests and feature requests are welcome!
If you encounter any issues, feel free to open an issue.

kmp-country-selector

kmp-country-selector Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

kmp-country-selector

kmp-country-selector Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README