Phone
An international phone number field: the country prefix and the number in one field.
Built to be filled in correctly
Floating label. The label rests where the number goes and lifts to the top of the field as soon as it has focus or a value.
Ghost digits. The country's example number shows faintly where the number goes, and the user's typing fills it in from the left — so the expected length and grouping are visible before the first digit, and how many digits remain is visible throughout.
Progress. A hairline along the bottom of the field fills as digits arrive and turns to the success color once the number is valid.
Confirmation. A valid number earns a check mark and a badge naming its kind — Mobile, Landline — so a user entering a landline where a mobile is wanted sees it before submitting.
Gentle validation. Errors wait until the field has been left (or validateWhileTyping is set): flagging an incomplete number on its third digit is accurate and hostile.
Each of these can be switched off through inputStyle.
What the caller gets
onValueChange delivers a complete PhoneNumberValue — formatted forms, e164Number and validity — so submission code never concatenates a dial code onto digits. That concatenation is wrong for every country with a national trunk prefix, and it is the bug this API exists to prevent.
Country changes keep the number
Switching country keeps the typed digits, re-formats them for the new region and re-validates them. A number valid in one region is never carried over as still valid in another — see PhoneNumberFieldState.selectCountry. A pasted or autofilled international number (+44…) switches the country itself.
Verification
Optional and decoupled. Pass a verificationController and the field shows progress and a verified mark, and drops verification as soon as the number changes. The library ships no verification backend — see com.ezzy.ccp.countrypicker.phone.PhoneNumberVerificationHandler.
Parameters
Field state. Hoist it to read the number or clear the field from outside.
Called whenever the number or country changes.
The field's container — CountrySelectorVariant.Elevated, Outlined, Filled, Underlined or Card. The pill variants are drawn as Elevated.
The floating label. Hidden by PhoneNumberInputStyle.labelMode = Hidden, but still announced, through accessibilityLabel.
The name announced for the number editor. Defaults to label; hiding the visible label never leaves the editor unnamed.
Shown in an empty field instead of the example number.
The phone field's own options — label, prefix, size, ghost digits, progress, badges. See PhoneNumberInputStyle.
A live helper line generated from the country's metadata: "Formats live for Kenya · e.g. +254 712 345 678".
Forces the error treatment — for a server-side rejection. Combined with the field's own validation rather than replacing it.
Overrides the derived validation message.
Called when the keyboard action fires on a valid number.