> ## 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.1).
  The API is subject to change before the stable release.
</Warning>

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`](/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`  | Localized country name for display.                                                         |
| `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.
</Note>

## Initializer

| Parameter  | Type      | Default | Description                      |
| ---------- | --------- | ------- | -------------------------------- |
| `code`     | `String`  | —       | ISO 3166-1 alpha-2 country code. |
| `name`     | `String`  | —       | Localized country name.          |
| `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`](/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. The session re-resolves `state.selectedCountry` into a full `PrimerCountry`:

```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`. |

<Tip>
  Pass the same ISO code you read from `country.code` to round-trip a selection, for example when restoring a saved billing address.
</Tip>

## 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

<CardGroup cols={2}>
  <Card title="PrimerCardFormSession" icon="credit-card" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session">
    Observe the card form state and update the billing country.
  </Card>

  <Card title="ValidationResult" icon="circle-check" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/common/validation-result">
    Field-level validation results for billing address inputs.
  </Card>
</CardGroup>