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

# Card Field Components

> Detailed reference for individual card and billing address field composables

<Warning>
  Primer Checkout Android SDK is currently in **beta** (v3.0.0-beta.4).
  The API is subject to change before the stable release.
</Warning>

Each `CardFormDefaults` field component handles its own formatting, validation, keyboard configuration, and error display. All fields accept `controller: PrimerCardFormController` and `modifier: Modifier = Modifier`.

## Card detail fields

### CardNumberField

| Aspect            | Detail                                                                                  |
| ----------------- | --------------------------------------------------------------------------------------- |
| Auto-formatting   | Groups digits with spaces (e.g., `4242 4242 4242 4242`)                                 |
| Max length        | 16-19 digits depending on detected network                                              |
| Keyboard type     | `KeyboardType.Number`                                                                   |
| Validation        | Luhn algorithm check, minimum length per network                                        |
| Validation timing | On blur (when user taps another field)                                                  |
| Trailing icon     | Detected card network logo(s) (Visa, Mastercard, Amex, etc.)                            |
| Network detection | Local detection begins after the 1st digit; remote detection begins after the 8th digit |

Supported networks: Visa, Mastercard, Amex, Diners Club, Discover, JCB, UnionPay, Maestro, Elo, Mir, Hiper, Hipercard, Cartes Bancaires, Dankort, Eftpos, Other.

### ExpiryField

| Aspect          | Detail                                              |
| --------------- | --------------------------------------------------- |
| Auto-formatting | Inserts `/` automatically (typing `1225` → `12/25`) |
| Max length      | 5 characters (MM/YY)                                |
| Keyboard        | `KeyboardType.Number`                               |
| Validation      | Valid month (01–12), future date                    |

### CvvField

| Aspect     | Detail                                           |
| ---------- | ------------------------------------------------ |
| Max length | 4 digits for Amex, 3 for other networks          |
| Keyboard   | `KeyboardType.Number`                            |
| Visual     | Password masking (dots)                          |
| Dynamic    | Max length updates when card network is detected |

### CardholderField

| Aspect     | Detail                                                        |
| ---------- | ------------------------------------------------------------- |
| Keyboard   | `KeyboardType.Text` with `KeyboardCapitalization.Words`       |
| Validation | Required (non-empty) when session requires cardholder name    |
| Visibility | Only rendered when `CARDHOLDER_NAME` is in `state.cardFields` |

### CardNetworkField

| Aspect                | Detail                                                       |
| --------------------- | ------------------------------------------------------------ |
| Visibility            | Only rendered when card has multiple networks (co-badged)    |
| Interaction           | Tapping a chip calls `controller.selectCardNetwork(network)` |
| No modifier parameter | Unlike other fields                                          |

## Billing address fields

All billing fields are rendered only when required by session configuration.

| Field               | Keyboard                        | Validation                         | Notes                                                   |
| ------------------- | ------------------------------- | ---------------------------------- | ------------------------------------------------------- |
| `CountryCodeField`  | —                               | Required                           | Read-only; opens picker via `requestCountrySelection()` |
| `FirstNameField`    | `Text` + `Words` capitalization | Required                           | —                                                       |
| `LastNameField`     | `Text` + `Words` capitalization | Required                           | —                                                       |
| `AddressLine1Field` | `Text`                          | Required                           | —                                                       |
| `AddressLine2Field` | `Text`                          | Optional                           | —                                                       |
| `CityField`         | `Text`                          | Required                           | —                                                       |
| `StateField`        | `Text`                          | Required                           | Label adapts to selected country                        |
| `PostalCodeField`   | `Text`                          | Required, format varies by country | Label adapts to selected country                        |

## Validation behavior

1. **While typing** — no error messages shown. `isFormValid` updates in real-time.
2. **On blur** — field is validated and any error is added to `state.fieldErrors`.
3. **Error display** — inline error text below the field using theme error color.
4. **Error clearing** — errors clear when corrected and re-validated on next blur.