# Pre-fill billing address checkbox

Learn how to configure the pre-fill billing address checkbox component.

## Basic usage

### Minimal configuration

The pre-fill billing address checkbox component copies shipping address values into billing fields. At minimum, you can create it with linked billing components:

```swift
import SwiftUI
import PXPCheckoutSDK

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 config = PrefillBillingAddressCheckboxComponentConfig(
    label: "Use shipping address for billing",
    checked: false,
    countrySelectionComponent: country,
    postcodeComponent: postcode,
    addressComponent: address
)

let prefill = try pxpCheckout.create(.prefillBillingAddressCheckbox, componentConfig: config) as! PrefillBillingAddressCheckboxComponent

VStack(alignment: .leading, spacing: 12) {
    prefill.buildContent()
    country.buildContent()
    postcode.buildContent()
    address.buildContent()
}
```

When checked, the component calls `CheckoutConfig.onGetShippingAddress` and copies the shipping values into the linked billing fields. When unchecked, it clears those fields.

### Inside billing address

You normally don't create this component directly. The billing address component creates it automatically when `allowPrefillBillingAddress` is enabled:

```swift
var prefillConfig = PrefillBillingAddressCheckboxComponentConfig(
    label: "Same as shipping address",
    checked: false,
    checkedColor: .accentColor
)

let config = BillingAddressComponentConfig(
    fields: BillingAddressComponentFields(
        prefillBillingAddressCheckbox: prefillConfig
    ),
    allowPrefillBillingAddress: true
)

let billing = try pxpCheckout.create(.billingAddress, componentConfig: config) as! BillingAddressComponent
```

### Advanced configuration

You can customise the checkbox styling and behaviour:

```swift
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 config = PrefillBillingAddressCheckboxComponentConfig(
    label: "Use shipping address for billing",
    labelStyles: CheckboxLabelStyles(
        checked: CheckboxLabelStyle(
            color: .primary,
            fontSize: 17,
            fontWeight: .semibold
        ),
        unchecked: CheckboxLabelStyle(
            color: .secondary,
            fontSize: 17,
            fontWeight: .regular
        )
    ),
    checkedColor: .accentColor,
    uncheckedColor: Color.secondary.opacity(0.5),
    size: 24,
    checked: false,
    countrySelectionComponent: country,
    postcodeComponent: postcode,
    addressComponent: address
)

let prefill = try pxpCheckout.create(.prefillBillingAddressCheckbox, componentConfig: config) as! PrefillBillingAddressCheckboxComponent
```

## Configuration

You can customise the checkbox appearance and linked components:

| Property | Description |
|  --- | --- |
| `countrySelectionComponent`CountrySelectionComponent? | The billing country field to pre-fill or clear. When the checkbox is checked, the country code from `onGetShippingAddress` is copied into this component. When unchecked, the field is cleared. Defaults to `nil`. |
| `postcodeComponent`PostcodeComponent? | The billing postcode field to pre-fill or clear. When the checkbox is checked, the postal code from `onGetShippingAddress` is copied into this component. When unchecked, the field is cleared. Defaults to `nil`. |
| `addressComponent`AddressComponent? | The billing address field to pre-fill or clear. When the checkbox is checked, the address from `onGetShippingAddress` is copied into this component. When unchecked, the field is cleared. Defaults to `nil`. |
| `label`String? | The checkbox label text. Displayed next to the checkbox. Defaults to SDK localisation. |
| `labelStyles`CheckboxLabelStyles? | The label styling for checked and unchecked states. Controls text colour and font based on checkbox state. States: `checked`, `unchecked`. Each state supports: `color`, `fontSize`, `fontWeight`. Defaults to `nil`. |
| `checkedColor`Color? | The checkbox colour when checked. Applied to the checkbox fill and checkmark. Defaults to `nil`. |
| `uncheckedColor`Color? | The checkbox colour when unchecked. Applied to the checkbox border. Defaults to `nil`. |
| `size`CGFloat? | The checkbox size in points. Controls both width and height of the checkbox. Defaults to `24`. |
| `checked`Bool | The initial checked state. When `true`, automatically pre-fills billing fields on first appearance. When `false`, fields remain empty until the user checks the box. Defaults to `false`. |


### `CheckboxLabelStyle`

| Property | Description |
|  --- | --- |
| `color`Color? | The label text colour. Defaults to `nil`. |
| `fontSize`CGFloat? | The label font size in points. Defaults to `nil`. |
| `fontWeight`Font.Weight? | The label font weight. Defaults to `nil`. |


## Behaviour

The pre-fill checkbox has smart behaviour:

- When checked, it calls `CheckoutConfig.onGetShippingAddress` and copies `countryCode`, `postalCode`, and `address` values into the linked billing fields.
- Values are passed through each field's `onBeforeChange` where applicable.
- After programmatic updates, validation may run, then the UI state is reset to `.base`.
- If the customer edits a billing field after pre-fill, the checkbox unchecks automatically.
- If they change values back to match the pre-filled values, the checkbox checks again.


## Shipping callback

Configure `onGetShippingAddress` in your checkout configuration to provide shipping address values:

```swift
let checkoutConfig = CheckoutConfig(
    environment: .test,
    session: sessionData,
    transactionData: transactionData,
    merchantShopperId: "shopper-1",
    ownerId: "owner-id",
    onGetShippingAddress: {
        ShippingAddress(
            countryCode: "GB",
            postalCode: "SW1A 1AA",
            address: "10 Downing Street"
        )
    }
)

let pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)
```

## Methods

### `buildContent()`

Returns SwiftUI content for the checkbox:

```swift
prefill.buildContent()
```

### `getValue() -> Bool`

Returns whether the checkbox is currently checked:

```swift
let isChecked = prefill.getValue()
```

## Examples

### Inside billing address

The most common usage is within the billing address component:

```swift
var prefillConfig = PrefillBillingAddressCheckboxComponentConfig(
    label: "Same as shipping address",
    checked: false
)

let config = BillingAddressComponentConfig(
    fields: BillingAddressComponentFields(
        prefillBillingAddressCheckbox: prefillConfig
    ),
    allowPrefillBillingAddress: true
)

let billing = try pxpCheckout.create(.billingAddress, componentConfig: config) as! BillingAddressComponent
```

### Standalone with custom styling

Create a standalone pre-fill checkbox with custom styling:

```swift
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 config = PrefillBillingAddressCheckboxComponentConfig(
    label: "Use my shipping address for billing",
    labelStyles: CheckboxLabelStyles(
        checked: CheckboxLabelStyle(
            color: .primary,
            fontSize: 15,
            fontWeight: .semibold
        ),
        unchecked: CheckboxLabelStyle(
            color: .secondary,
            fontSize: 15,
            fontWeight: .regular
        )
    ),
    checkedColor: .blue,
    uncheckedColor: .gray.opacity(0.4),
    size: 22,
    checked: false,
    countrySelectionComponent: country,
    postcodeComponent: postcode,
    addressComponent: address
)

let prefill = try pxpCheckout.create(.prefillBillingAddressCheckbox, componentConfig: config) as! PrefillBillingAddressCheckboxComponent

VStack(alignment: .leading, spacing: 12) {
    prefill.buildContent()
    country.buildContent()
    postcode.buildContent()
    address.buildContent()
}
```

### Pre-checked on load

Start with the checkbox checked to auto-fill on first appearance:

```swift
var config = PrefillBillingAddressCheckboxComponentConfig(
    label: "Same as shipping address",
    checked: true,
    countrySelectionComponent: country,
    postcodeComponent: postcode,
    addressComponent: address
)

let prefill = try pxpCheckout.create(.prefillBillingAddressCheckbox, componentConfig: config) as! PrefillBillingAddressCheckboxComponent
```

### With shipping callback

Configure the checkout to provide shipping address data:

```swift
let checkoutConfig = CheckoutConfig(
    environment: .test,
    session: sessionData,
    transactionData: transactionData,
    merchantShopperId: "shopper-1",
    ownerId: "owner-id",
    onGetShippingAddress: {
        ShippingAddress(
            countryCode: "US",
            postalCode: "10001",
            address: "123 Main Street, Apt 4B"
        )
    }
)

let pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)

var prefillConfig = PrefillBillingAddressCheckboxComponentConfig(
    label: "Same as shipping address",
    checked: false
)

let billingConfig = BillingAddressComponentConfig(
    fields: BillingAddressComponentFields(
        prefillBillingAddressCheckbox: prefillConfig
    )
)

let billing = try pxpCheckout.create(.billingAddress, componentConfig: billingConfig) as! BillingAddressComponent
```

### Disable pre-fill

Hide the pre-fill checkbox by setting `allowPrefillBillingAddress` to `false`:

```swift
let config = BillingAddressComponentConfig(
    allowPrefillBillingAddress: false
)

let billing = try pxpCheckout.create(.billingAddress, componentConfig: config) as! BillingAddressComponent
```

For full billing address integration, see [Billing address](/guides/checkout/components/ios/card/billing-address). For individual field configuration, see [Country selection](/guides/checkout/components/ios/card/country-selection), [Postcode](/guides/checkout/components/ios/card/postcode), and [Address](/guides/checkout/components/ios/card/address).