Customizations

State Configuration

Use rememberKomposeCountryCodePickerState() to create and configure the picker state:

val state = rememberKomposeCountryCodePickerState(
    defaultCountryCode = "KE",
    limitedCountries = listOf("KE", "UG", "TZ", "RW"),
    priorityCountries = listOf("KE", "UG", "TZ"),
    showCountryCode = true,
    showCountryFlag = true,
)

State Parameters

Parameter	Type	Default	Description
defaultCountryCode	String?	Auto-detected	The default country code (ISO 3166-1 alpha-2). When null, the library auto-detects the user's country on all platforms.
limitedCountries	List<String>	emptyList()	Limits which countries appear in the picker. Accepts country codes ("KE"), country names ("Kenya"), or phone codes ("+254"). An empty list shows all countries.
priorityCountries	List<String>	emptyList()	Country codes to display at the top of the list (e.g. listOf("KE", "UG", "TZ")). Must be ISO country codes.
showCountryCode	Boolean	true	Whether to display the dialling code (e.g. +254) next to the flag.
showCountryFlag	Boolean	true	Whether to display the country flag.

Tip

Default country detection works on all platforms: it uses Locale on Android/JVM, NSLocale on iOS, and browser language/timezone on JS/WasmJS.

TextField Customizations

The KomposeCountryCodePicker composable accepts the following parameters:

Parameter	Type	Default	Description
state	CountryCodePicker	—	The state object from rememberKomposeCountryCodePickerState(). Required.
text	String	—	The current phone number text. Required.
modifier	Modifier	Modifier	Modifier applied to the text field layout.
onValueChange	(String) -> Unit	{}	Called when the text field value changes.
error	Boolean	false	Whether to display the text field in an error state.
showOnlyCountryCodePicker	Boolean	false	If true, renders only the country picker without the text field.
shape	Shape	MaterialTheme.shapes.medium	The shape of the text field outline.
placeholder	@Composable (String) -> Unit	Default hint	A composable to display as the placeholder. Receives the current country code.
colors	TextFieldColors	TextFieldDefaults.colors()	Colors for the text field.
trailingIcon	@Composable (() -> Unit)?	null	An optional trailing icon composable.
leadingIconContainerColor	Color	Color.Unspecified	Background color of the country selector area. When Color.Unspecified, no background is drawn.
interactionSource	MutableInteractionSource	MutableInteractionSource()	The interaction source for the text field.
selectedCountryFlagSize	FlagSize	FlagSize(28.dp, 18.dp)	The width and height of the selected country flag.
textStyle	TextStyle	LocalTextStyle.current	The text style for the phone number text field. Also used for the country code when countryCodeTextStyle is not set.
countryCodeTextStyle	TextStyle?	null	The text style for the country code text (e.g. "+254"). When null, falls back to textStyle.
enabled	Boolean	true	Whether the text field and country picker are enabled.
keyboardOptions	KeyboardOptions	Phone / Next	Keyboard options for the text field. Defaults to phone keyboard with ImeAction.Next.
selectedCountryPadding	Dp	8.dp	Padding around the selected country component. Useful for removing extra spacing when embedding the picker inside a custom text field's decorator box.
keyboardActions	KeyboardActions	KeyboardActions.Default	Keyboard actions for the text field.

Dialog Customizations

The country selection dialog can be customized through additional parameters on KomposeCountryCodePicker:

Parameter	Type	Default	Description
countrySelectionDialogContainerColor	Color	MaterialTheme.colorScheme.background	Background color of the dialog.
countrySelectionDialogContentColor	Color	MaterialTheme.colorScheme.onBackground	Content/text color of the dialog.
countrySelectionDialogTitle	@Composable () -> Unit	"Select Country"	A composable for the dialog title.
countrySelectionDialogBackIcon	@Composable () -> Unit	Back arrow icon	A composable for the back/dismiss button icon.
countrySelectionDialogSearchIcon	@Composable () -> Unit	Search icon	A composable for the search toggle icon.
dropDownIcon	@Composable () -> Unit	Down arrow icon	A composable for the dropdown indicator next to the selected country. Tinted by LocalContentColor by default.

The dialog is responsive: it displays full-screen on compact screens (width < 600dp) and as a popup on larger screens.

CountrySelectionDialog (Standalone)

The CountrySelectionDialog composable is part of the public API and can be used independently. This is useful when you have your own text field component and want to use the library only for the searchable country list and flag assets — without the built-in OutlinedTextField that KomposeCountryCodePicker provides.

When a country is selected, call state.setCode(country.code) to update the state, then use state.selectedCountry to access the selected country's flag, name, and phoneNoCode in your own layout. See the Fully Custom Phone Input section for a complete example.

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

Parameter	Type	Default	Description
countryList	List<Country>	—	The list of countries to display. Required.
containerColor	Color	—	Background color of the dialog. Required.
contentColor	Color	—	Content/text color of the dialog. Required.
onDismissRequest	() -> Unit	—	Called when the user dismisses the dialog. Required.
onSelect	(Country) -> Unit	—	Called when a country is selected. Required.
modifier	Modifier	Modifier	Modifier applied to the dialog layout.
properties	DialogProperties	Full-width	Dialog window properties.
title	@Composable () -> Unit	"Select Country"	A composable for the dialog title.
backIcon	@Composable () -> Unit	Back arrow icon	A composable for the back button icon.
searchIcon	@Composable () -> Unit	Search icon	A composable for the search icon.