Country selection

Learn how to configure the country selection component.

Basic usage

Minimal configuration

The country selection component displays a searchable drop-down for selecting a country. At minimum, you can create it with a label:

import SwiftUI
import PXPCheckoutSDK

let config = CountrySelectionComponentConfig(
    label: "Country",
    placeholder: "Select country"
)

let country = try pxpCheckout.create(.countrySelection, componentConfig: config) as! CountrySelectionComponent

country.buildContent()

Advanced configuration

You can customise the dropdown styling, validation messages, and event handlers:

var config = CountrySelectionComponentConfig(
    label: "Country",
    placeholder: "Search or select",
    guideText: "Billing country",
    noCountryText: "No matching country",
    validations: CountrySelectionValidationResource(CS01: "Select a country"),
    dropdownStyles: CountrySelectionDropdownStyles(
        maxHeight: 280,
        cornerRadius: 8,
        selectedOptionStyle: CountrySelectionOptionStyle(
            backgroundColor: Color.blue.opacity(0.12),
            textColor: .primary
        ),
        unselectedOptionStyle: CountrySelectionOptionStyle(
            verticalPadding: 10,
            horizontalPadding: 12
        ),
        emptyStateStyle: CountrySelectionOptionStyle(
            textColor: .secondary
        )
    ),
    onChange: { /* selection changed */ },
    onValidationFailed: { _ in }
)

config.componentStyles = FieldStyle(cornerRadius: 8)
config.displayValidIcon = true
config.validationOnChange = true

let country = try pxpCheckout.create(.countrySelection, componentConfig: config) as! CountrySelectionComponent

Property	Description
`validations` CountrySelectionValidationResource?	Custom validation messages for CS01 error code. Overrides SDK default message. Defaults to `nil`.
`noCountryText` String?	The message displayed when search matches no country. Shown in the dropdown when the user's search query has no results. Defaults to SDK localisation.
`dropdownStyles` CountrySelectionDropdownStyles?	The dropdown panel and option styling. Controls the appearance of the country selection dropdown menu. Defaults to `nil`.
`label` String?	The field label text. Defaults to `nil`.
`placeholder` String?	The placeholder text shown when no country is selected. Displayed in the dropdown trigger. Defaults to `nil`.
`guideText` String?	The helper text displayed below the field. Defaults to `nil`.
`accessibilityLabel` String?	The accessibility label for the control. Defaults to `nil`.
`isRequired` Bool	Whether the field is required. For the country selection component, this is always `true` and can't be changed. A country must be selected before the payment can be submitted.
`componentStyles` FieldStyle?	The container styling. Defaults to `nil`. Properties: `color`, `font`, `fontWeight`, `fontSize`, `labelFont`, `labelColor`, `valueFont`, `valueColor`, `backgroundColor`, `borderColor`, `borderWidth`, `cornerRadius`, `padding`, `margin`, `textAlignment`, `opacity`, `shadow` (ShadowStyle), `icon` (IconStyle), `labelSpacing`.
`inputStyles` FieldInputStateStyles?	The input styling for different states. Defaults to `nil`. States: `base` (default unfocused), `active` (focused), `valid` (has valid value), `invalid` (has invalid value). Each state supports: `color`, `placeholderColor`, `fontWeight`, `fontSize`, `backgroundColor`, `borderColor`, `borderWidth`, `cornerRadius`, `padding`, `minHeight`.
`labelStyles` FieldLabelStateStyles?	The label styling by state. Defaults to `nil`. States: `base` (default), `active` (focused), `valid` (has valid value), `invalid` (has invalid value). Each state supports: `color`, `font`. Additional property: `minWidth` (CGFloat? - default: 80).
`labelPosition` LabelPosition?	The label position relative to input. Options: `above`, `below`, `left`, `right`. Defaults to `nil`.
`invalidTextStyle` FieldMessageStyle?	The error message styling. Defaults to `nil`. Properties: `color`, `font`.
`invalidTextPosition` TextPosition?	The error message placement. Defaults to `nil`.
`guideTextStyle` FieldMessageStyle?	The guide text styling. Defaults to `nil`. Properties: `color`, `font`.
`invalidIcon` Image?	The custom invalid state icon. Defaults to `nil`.
`validIcon` Image?	The custom valid state icon. Defaults to `nil`.
`displayValidIcon` Bool	Whether to show the valid icon. Defaults to `false`.
`displayInvalidIcon` Bool	Whether to show the invalid icon. Defaults to `true`.
`tooltipAccessibilityLabel` String?	The tooltip accessibility label. Defaults to `nil`.
`displayRequiredIcon` Bool?	Whether to display the required indicator. Defaults to `nil`.
`allowToCopyPaste` Bool	Whether to allow copy and paste. Defaults to `true`.
`validationOnBlur` Bool	Whether to validate when the field loses focus. Defaults to `true`.
`validationOnChange` Bool	Whether to validate on each change. Defaults to `false`.
`isDisabled` Bool	Whether the field is disabled. Defaults to `false`.

You can customise the dropdown panel and option rows:

`CountrySelectionDropdownStyles`

Property	Description
`backgroundColor` Color?	The dropdown panel background colour. Defaults to `nil`.
`borderColor` Color?	The panel border colour. Defaults to `nil`.
`borderWidth` CGFloat?	The panel border width in points. Defaults to `nil`.
`cornerRadius` CGFloat?	The panel corner radius in points. Defaults to `nil`.
`shadow` ShadowStyle?	The panel shadow configuration. Properties: `color`, `radius`, `x`, `y`. Defaults to `nil`.
`maxHeight` CGFloat?	The maximum scroll height in points. Limits the vertical size of the dropdown list. Defaults to `nil`.
`selectedOptionStyle` CountrySelectionOptionStyle?	The styling for the currently selected option. Defaults to `nil`.
`unselectedOptionStyle` CountrySelectionOptionStyle?	The styling for unselected options in the dropdown. Defaults to `nil`.
`emptyStateStyle` CountrySelectionOptionStyle?	The styling for empty search state display. Shown when no countries match the search query. Defaults to `nil`.

`CountrySelectionOptionStyle`

Property	Description
`backgroundColor` Color?	The option row background colour. Defaults to `nil`.
`textColor` Color?	The country name text colour. Defaults to `nil`.
`font` Font?	The country name font. Defaults to `nil`.
`horizontalPadding` CGFloat?	The row horizontal padding in points. Defaults to `nil`.
`verticalPadding` CGFloat?	The row vertical padding in points. Defaults to `nil`.

Event handling

The country selection component provides event handlers for user interaction and validation:

Callback	Description
`onChange: (() -> Void)?`	Called when the selection changes.
`onFocus: (() -> Void)?`	Called when the field gains focus.
`onBlur: (() -> Void)?`	Called when the field loses focus.
`onValidationPassed: (([ValidationResult]) -> Void)?`	Called when validation passes. Receives an array of validation results.
`onValidationFailed: (([ValidationResult]) -> Void)?`	Called when validation fails. Receives an array of validation results containing error details.

For more information about event patterns, see Events.

Validation

The country selection component validates user input against the following rules:

Code	Condition	Default message
CS01	Required but no country selected	"Please select country"

Validation triggers based on your configuration (validationOnBlur, validationOnChange). Override the default message using the validations property.

Methods

`buildContent()`

Returns SwiftUI content for the country selection dropdown:

country.buildContent()

Examples

Configure custom styling for the dropdown panel and options:

var config = CountrySelectionComponentConfig(label: "Country")
config.dropdownStyles = CountrySelectionDropdownStyles(
    maxHeight: 200,
    borderColor: Color(.separator),
    borderWidth: 1,
    selectedOptionStyle: CountrySelectionOptionStyle(
        backgroundColor: .blue.opacity(0.1),
        textColor: .primary
    )
)
let country = try pxpCheckout.create(.countrySelection, componentConfig: config) as! CountrySelectionComponent

With billing address

Use in combination with other billing fields:

let country = try pxpCheckout.create(
    .countrySelection,
    componentConfig: CountrySelectionComponentConfig(label: "Country")
) as! CountrySelectionComponent

let postcode = try pxpCheckout.create(
    .postcode,
    componentConfig: PostcodeComponentConfig(label: "Postcode")
) as! PostcodeComponent

let address = try pxpCheckout.create(
    .address,
    componentConfig: AddressComponentConfig(label: "Address")
) as! AddressComponent

var submitConfig = CardSubmitComponentConfig()
submitConfig.avsRequest = true
submitConfig.billingAddressComponents = BillingAddressComponents(
    countrySelectionComponent: country,
    postcodeComponent: postcode,
    addressComponent: address
)

Use this component in Billing address or wider address flows. For validation details, see Data validation.

Country selection

Basic usage

Minimal configuration

Advanced configuration

Dropdown styles

CountrySelectionDropdownStyles

CountrySelectionOptionStyle