> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PrimerCountry

> Country data type for billing address selection

> [!WARNING]
>
> Primer Checkout iOS SDK is currently in **beta** (v3.0.0-beta.8).
> The API is subject to change before the stable release.

Represents a country in the card form's billing address flow. `PrimerCountry` carries the ISO code, display name, flag emoji, and dial code, and is surfaced through [`PrimerCardFormState.selectedCountry`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session) once the buyer selects a country.

`PrimerCountry` is a `public struct` conforming to `Equatable` and `Identifiable`, where `id` is the ISO `code`. The stable identifier makes it safe to use directly in SwiftUI `List` and `ForEach`.

## Definition

```swift theme={"dark"}
@available(iOS 15.0, *)
public struct PrimerCountry: Equatable, Identifiable {
    public var id: String { code }
    public let code: String
    public let name: String
    public let flag: String?
    public let dialCode: String?

    public init(code: String, name: String, flag: String? = nil, dialCode: String? = nil)
}
```

## Properties

| Property | Type | Description |
| - | - | - |
| `id` | `String` | Deterministic identifier based on country code for stable SwiftUI diffing. Equal to `code`. |
| `code` | `String` | ISO 3166-1 alpha-2 country code (e.g., `"US"`, `"GB"`, `"DE"`). |
| `name` | `String` | Country name for display. In `state.selectedCountry` this is the English name from the SDK's dial-code table (for example `"United States"`), not a localized name. When you create a `PrimerCountry` yourself, it is the value you pass. |
| `flag` | `String?` | Flag emoji for the country (e.g., `"🇺🇸"`). `nil` when unavailable. |
| `dialCode` | `String?` | International dialing code (e.g., `"+1"` for US). `nil` when unavailable. |

> [!NOTE]
>
> `PrimerCountry` requires iOS 15.0+, matching the minimum deployment target for the Checkout Components framework.

## Initializer

| Parameter | Type | Default | Description |
| - | - | - | - |
| `code` | `String` | — | ISO 3166-1 alpha-2 country code. |
| `name` | `String` | — | Country name for display. |
| `flag` | `String?` | `nil` | Flag emoji for the country. |
| `dialCode` | `String?` | `nil` | International dialing code. |

## Reading the selected country

When billing address collection is enabled, the buyer's chosen country is exposed on the card form state. Observe [`PrimerCardFormSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session) and read `state.selectedCountry`:

```swift theme={"dark"}
struct BillingCountryLabel: View {
    @ObservedObject var session: PrimerCardFormSession

    var body: some View {
        if let country = session.state.selectedCountry {
            HStack {
                Text(country.flag ?? "")
                Text(country.name)
                Text("(\(country.code))")
                    .foregroundStyle(.secondary)
            }
        } else {
            Text("Select a country")
        }
    }
}
```

## Updating the selected country

To set the billing country programmatically, call `updateCountryCode(_:)` on the card form session with an ISO 3166-1 alpha-2 code. When the code is a supported country code with a dial-code entry, the session resolves `state.selectedCountry` into a full `PrimerCountry`. Otherwise, `state.selectedCountry` keeps its previous value. The codes BQ, BV, CW, EH, HM, SX, TF and UM have no dial-code entry. The buyer can pick them in the country picker, but `state.selectedCountry` keeps its previous value:

```swift theme={"dark"}
session.updateCountryCode("US")
```

| Method | Description |
| - | - |
| `updateCountryCode(_ value: String)` | Updates the billing country by ISO 3166-1 alpha-2 code. Updates `state.selectedCountry` when the code is a supported country code with a dial-code entry; otherwise `state.selectedCountry` keeps its previous value. |

> [!TIP]
>
> Pass the same ISO code you read from `country.code` to round-trip a selection, for example when restoring a saved billing address.

## Equatable behavior

Two `PrimerCountry` values are equal when all four properties (`code`, `name`, `flag`, `dialCode`) match. This makes `PrimerCountry` safe to compare when diffing card form state in `Equatable`-driven SwiftUI views.

## See also

> [card] [PrimerCardFormSession](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session.md)
>
> Observe the card form state and update the billing country.

> [card] [Validation](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/validation-result.md)
>
> Field-level validation errors (`FieldError`) for billing address inputs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.