`PhoneNumberInput`¶

The original phone-number component. Its public API is unchanged; the implementation now runs on the Country Picker foundation.

Basic usage¶

PhoneNumberInput(
    onValueChange = { phone ->
        phone.formattedPhone  // "+254 724 154 958"
        phone.phoneNumber     // "+254724154958" (E.164; empty while unparseable)
        phone.country         // SelectedCountry(name, code, dialCode, flag)
        phone.isValid         // true / false
    },
)

State hoisting¶

Hoist PhoneState when you need to read state or drive the field from outside the composable, for example to clear it after submission or to validate on a button tap.

val phoneState = rememberPhoneState()

PhoneNumberInput(state = phoneState, onValueChange = { phone -> /* … */ })

Button(onClick = {
    if (phoneState.isValid) submit(phoneState.toPhone()) else phoneState.clearPhone()
}) { Text("Submit") }

// Default: modal bottom sheet
PhoneNumberInput(
    ccpConfig = CCPDefaults.defaultConfig(countryPickerStyle = CountryPickerStyle.BottomSheet),
)

// Compact inline dropdown (tablets, landscape, dense forms)
PhoneNumberInput(
    ccpConfig = CCPDefaults.defaultConfig(countryPickerStyle = CountryPickerStyle.Dropdown),
)

In the BottomSheet style the field is a real Material outlined text field with the flag, dial code and chevron as leading content and a subtle divider before the number editor. The floating label and the divider are independently togglable with showLabel (off by default) and showPhonePrefixDivider (on by default). The Dropdown style keeps its original compact selector button with a popup anchored below it.

Error state¶

var isError by remember { mutableStateOf(false) }

PhoneNumberInput(
    isError = isError,
    errorMessage = "Please enter a valid phone number",
    onValueChange = { phone -> isError = !phone.isValid && phone.phoneNumber.isNotEmpty() },
)

Pre-fill and country override¶

PhoneNumberInput(
    value = "+254724154958",   // pre-fill in E.164; the country is taken from it
    setCountry = "KE",         // or force a country by ISO code or name ("Kenya")
)

Country filtering¶

PhoneNumberInput(
    countriesToShow = listOf("US", "GB", "KE", "FR", "AU"),   // allow list
    countriesExclude = listOf("KP", "IR"),                    // exclusions win
    pinnedCountries = listOf("US", "GB", "KE"),               // "Suggested" section at the top
)

Behaviour options¶

PhoneNumberInput(
    ccpConfig = CCPDefaults.defaultConfig(
        showClearButton = true,        // × inside the field
        autoDetectCountry = true,      // SIM → network → locale → default
        enforceMaxLength = false,      // default true: cap digits at the country's max
        defaultCountryListStyle = CountryListStyle.Grid,   // or List
        showLabel = true,              // floating label (BottomSheet style)
        phoneFieldSize = PhoneFieldSize.Compact,
    ),
    label = "Mobile number",
    onDone = { submitForm() },         // only when isValid
)

Colors, shapes and typography¶

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,
    ),
    ccpConfig = CCPDefaults.defaultConfig(
        phoneInputShape = RoundedCornerShape(8.dp),
        borderWidth = 1.dp,
        showCountryFlag = true,
        showHeader = true,
        showCountriesHeaderDivider = true,
    ),
)

Reference¶