# Country selection

Learn about customisation options for the country selection component.

## Styling

```kotlin
val countrySelectionComponentConfig = CountrySelectionComponentConfig(
    isRequired = Boolean,
    availableCountries = List<Country>,
    defaultCountry = String,
    showFlags = Boolean,
    searchPlaceholderText = String,
    noCountryText = String,
    style = CountrySelectionStyle?,
    label = String,
    placeholder = String,
    showTrailingIcon = Boolean,
    showValidIcon = Boolean,
    validIcon = Int,
    invalidIcon = Int,
    showInvalidIcon = Boolean,
    validations = CountrySelectionValidations
)
```

| Property | Description |
|  --- | --- |
| `isRequired`Boolean | Whether country selection is required. Defaults to `true`. |
| `availableCountries`List<Country> | The list of selectable countries. Defaults to an empty list (i.e., all countries available). |
| `defaultCountry`String | The default selected country code. Defaults to an empty string. |
| `showFlags`Boolean | Whether to display country flags. Defaults to `true`. |
| `searchPlaceholderText`String | The placeholder text for the search field in the dropdown. |
| `noCountryText`String | The text to display when no country is found. |
| `style`CountrySelectionStyle? | Country selection styling configuration. |
| `label`String | The display label shown above the country selection field. |
| `placeholder`String | The placeholder text shown when no country is selected. |
| `showTrailingIcon`Boolean | Whether to show a trailing dropdown icon. Defaults to `true`. |
| `showValidIcon`Boolean | Whether to show a validation icon when valid. Defaults to `false`. |
| `validIcon`Int | The valid icon resource. |
| `invalidIcon`Int | The invalid icon resource. |
| `showInvalidIcon`Boolean | Whether to show an invalid icon when invalid. Defaults to `true`. |
| `validations`CountrySelectionValidations | Custom validation error messages. |


## Callbacks

```kotlin
data class CountrySelectionComponentConfig(
    val onChange: ((String) -> Unit)? = null,
    val onFocus: (() -> Unit)? = null,
    val onValidationPassed: ((List<ValidationResult>) -> Unit)? = null,
    val onValidationFailed: ((List<ValidationResult>) -> Unit)? = null
)
```

| Callback | Description |
|  --- | --- |
| `onChange: (String) -> Unit` | Event handler for when the selected country changes. |
| `onFocus: () -> Unit` | Event handler for when the input receives focus. |
| `onValidationPassed: (List<ValidationResult>) -> Unit` | Event handler for when validation passes. |
| `onValidationFailed: (List<ValidationResult>) -> Unit` | Event handler for when validation fails. |


For more information about callbacks, see [Events](/guides/checkout/components/android/card/events).

## Example

```kotlin
import com.pxp.checkout.components.countryselection.CountrySelectionComponent
import com.pxp.checkout.components.countryselection.CountrySelectionComponentConfig
import com.pxp.checkout.components.countryselection.Country
import com.pxp.checkout.components.countryselection.CountrySelectionValidations
import com.pxp.checkout.components.countryselection.CountrySelectionStyle

// Optional: Define available countries (if you want to limit the selection)
val supportedCountries = listOf(
    Country("US", "United States", "🇺🇸"),
    Country("CA", "Canada", "🇨🇦"),
    Country("GB", "United Kingdom", "🇬🇧"),
    Country("DE", "Germany", "🇩🇪"),
    Country("FR", "France", "🇫🇷"),
    Country("AU", "Australia", "🇦🇺"),
    Country("JP", "Japan", "🇯🇵")
)

val config = CountrySelectionComponentConfig(
    // Basic configuration
    label = "Country of Residence",
    placeholder = "Choose your country",
    isRequired = true,
    
    // Country list configuration (optional - defaults to all countries)
    availableCountries = supportedCountries,
    defaultCountry = "US",
    
    // UI configuration
    showFlags = true,
    searchPlaceholderText = "Search countries...",
    noCountryText = "No countries found",
    
    // Icon configuration
    showTrailingIcon = true,
    showValidIcon = false,
    showInvalidIcon = true,
    validIcon = R.drawable.ic_check,
    invalidIcon = R.drawable.ic_invalid,
    
    // Validation configuration
    validations = CountrySelectionValidations(
        required = "Please select your country"
    ),
    
    // Custom styling (optional)
    style = CountrySelectionStyle(
        dropdownBackgroundColor = Color.White,
        dropdownBorderColor = Color.Gray,
        selectedItemColor = Color.Blue,
        flagSize = 24.dp,
        itemPadding = 12.dp,
        cornerRadius = 8.dp
    )
)

val countrySelectionComponent = checkout.createComponent<CountrySelectionComponent, CountrySelectionComponentConfig>(
    type = ComponentType.COUNTRY_SELECTION,
    config = config
)
```