# Card brand selector

Learn how to configure the card brand selector component.

## Basic usage

### Minimal configuration

The card brand selector displays card brand logos and updates as the customer types. At minimum, you can create it and link it to a card number field:

```swift
import SwiftUI
import PXPCheckoutSDK

let brandConfig = CardBrandSelectorComponentConfig()
let brandSelector = try pxpCheckout.create(.cardBrandSelector, componentConfig: brandConfig) as! CardBrandSelectorComponent

var cardNumberConfig = CardNumberComponentConfig(
    label: "Card number",
    acceptedCardBrands: [.visa, .mastercard, .amex, .discover]
)
cardNumberConfig.cardBrandSelectorComponent = brandSelector

let cardNumber = try pxpCheckout.create(.cardNumber, componentConfig: cardNumberConfig) as! CardNumberComponent

VStack(alignment: .leading, spacing: 8) {
    cardNumber.buildContent()
}
```

The card number component automatically updates the brand selector as the customer types. You don't need to manually trigger updates.

### Advanced configuration

You can customise display modes, brand images, and accessibility text:

```swift
var brandConfig = CardBrandSelectorComponentConfig()
brandConfig.useDefaultMode = true
brandConfig.includeAcceptedCardBrandsInDefaultMode = true
brandConfig.showOnlyRecognisedCardBrand = false
brandConfig.unrecognisedCardNumberAltText = "Unknown card type"
brandConfig.useTransparentCardBrandImage = true

brandConfig.defaultCardImage = CardImageConfig(
    image: Image("CustomGenericCard"),
    width: 40,
    height: 25
)

brandConfig.cardBrandImages = [
    .visa: CardImageConfig(image: Image("CustomVisa"), width: 40, height: 25),
    .mastercard: CardImageConfig(image: Image("CustomMC"), width: 40, height: 25),
    .amex: CardImageConfig(image: Image("CustomAmex"), width: 40, height: 25)
]

let brandSelector = try pxpCheckout.create(.cardBrandSelector, componentConfig: brandConfig) as! CardBrandSelectorComponent
```

| Property | Description |
|  --- | --- |
| `useDefaultMode`Bool? | Whether to show the accepted brands and highlight the recognised one. Set to `false` for a minimal layout. Defaults to `true`. |
| `showOnlyRecognisedCardBrand`Bool? | Whether to show only the recognised brand in non-default mode. When `true`, only the detected card brand is displayed. Defaults to `false`. |
| `includeAcceptedCardBrandsInDefaultMode`Bool? | Whether to show the accepted brands row in default mode. When `true`, displays all accepted card brands alongside the highlighted recognised brand. Defaults to `false`. |
| `unrecognisedCardNumberAltText`String? | The accessibility text for unrecognised card brands. This text is announced by screen readers when the card type can't be determined. Defaults to `nil`. |
| `defaultCardImage`CardImageConfig? | The image configuration for unrecognised card brands. Displayed when the card type can't be determined from the entered number. Defaults to `nil`. Properties: `image` (Image?), `width` (CGFloat?), `height` (CGFloat?). |
| `cardBrandImages`[CardBrandType: CardImageConfig]? | The custom images for specific card brands. Supports Visa, Mastercard, Amex, UnionPay (CUP), Diners, Discover, and JCB. Each brand can have custom image configuration with width and height. Defaults to `nil`. |
| `useTransparentCardBrandImage`Bool? | Whether to use transparent brand images. When `true`, brand logos render without background colours. Defaults to `true`. |


### `CardImageConfig`

| Property | Description |
|  --- | --- |
| `image`Image? | The SwiftUI Image to display. Can be an asset image or system image. Defaults to `nil`. |
| `width`CGFloat? | The image width in points. Defaults to `nil`. |
| `height`CGFloat? | The image height in points. Defaults to `nil`. |


## Display modes

The card brand selector supports two display modes:

**Default mode:** Shows accepted brands and highlights the detected brand. Set `includeAcceptedCardBrandsInDefaultMode` to `true` to display all accepted brands.

**Dynamic mode:** A minimal layout that focuses on the detected brand. Set `useDefaultMode` to `false` and `showOnlyRecognisedCardBrand` to `true` to show only the detected brand.

## Styling

You can customise brand images using SwiftUI `Image` values:

```swift
brandConfig.defaultCardImage = CardImageConfig(
    image: Image("CustomGenericCard"),
    width: 40,
    height: 25
)

brandConfig.cardBrandImages = [
    .visa: CardImageConfig(image: Image("CustomVisa"), width: 40, height: 25),
    .mastercard: CardImageConfig(image: Image("CustomMC"), width: 40, height: 25)
]
```

## Methods

### `buildContent()`

Returns SwiftUI content for the brand selector:

```swift
brandSelector.buildContent()
```

## Examples

### Dynamic mode, recognised brand only

Show only the detected brand in a minimal layout:

```swift
var cfg = CardBrandSelectorComponentConfig()
cfg.useDefaultMode = false
cfg.showOnlyRecognisedCardBrand = true
let selector = try pxpCheckout.create(.cardBrandSelector, componentConfig: cfg) as! CardBrandSelectorComponent
```

### Using the convenience initializer

Configure the brand selector with multiple options at once:

```swift
let cfg = CardBrandSelectorComponentConfig(
    useDefaultMode: true,
    includeAcceptedCardBrandsInDefaultMode: true,
    unrecognisedCardNumberAltText: "Card not recognised",
    defaultCardImage: CardImageConfig(width: 40, height: 25),
    useTransparentCardBrandImage: true
)
let selector = try pxpCheckout.create(.cardBrandSelector, componentConfig: cfg) as! CardBrandSelectorComponent
```

### With card submit

Link the card number component (with embedded selector) to card submit:

```swift
var cardNumberConfig = CardNumberComponentConfig(
    label: "Card number",
    acceptedCardBrands: [.visa, .mastercard, .amex]
)
cardNumberConfig.cardBrandSelectorComponent = brandSelector
let cardNumber = try pxpCheckout.create(.cardNumber, componentConfig: cardNumberConfig) as! CardNumberComponent

var submitConfig = CardSubmitComponentConfig()
submitConfig.cardNumberComponent = cardNumber
submitConfig.onPreAuthorisation = { _ async in TransactionInitiationData() }
submitConfig.onPostAuthorisation = { _ in }

let submit = try pxpCheckout.create(.cardSubmit, componentConfig: submitConfig) as! CardSubmitComponent
```

Supported card brands: Visa, Mastercard, Amex, UnionPay (CUP), Diners, Discover, and JCB.