Address

Learn how to configure the address component.

Basic usage

Minimal configuration

The address component collects a single street address line. At minimum, you can create it with default settings:

import SwiftUI
import PXPCheckoutSDK

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

let address = try pxpCheckout.create(
    .address,
    componentConfig: AddressComponentConfig()
) as! AddressComponent

address.buildContent()

Advanced configuration

You can customise labels, placeholders, validation messages, and styling:

var config = AddressComponentConfig(
    label: "Street address",
    placeholder: "123 Main Street, Apt 4B",
    guideText: "Include flat or unit number if applicable",
    accessibilityLabel: "Billing street address",
    validations: AddressValidationResource(
        AD01: "Please enter your street address",
        AD02: "Address cannot exceed 100 characters"
    )
)

config.labelPosition = .above
config.validationOnBlur = true
config.validationOnChange = false
config.displayValidIcon = true
config.componentStyles = FieldStyle(
    cornerRadius: 8,
    padding: EdgeInsets(top: 8, leading: 0, bottom: 8, trailing: 0)
)

let address = try pxpCheckout.create(.address, componentConfig: config) as! AddressComponent

Property	Description
`validations` AddressValidationResource?	Custom validation messages for the required field check (AD01) and the maximum length check (AD02). Defaults to SDK localisation.
`isRequired` Bool	Whether the field is required. Always `true` for address; this field must have a value before the payment can be submitted.
`label` String?	The label text displayed for the field. Defaults to `nil`.
`placeholder` String?	The placeholder text shown when the field is empty. Defaults to `nil`.
`guideText` String?	The helper text displayed below the field. Defaults to `nil`.
`accessibilityLabel` String?	The accessibility label for the input field. Defaults to `nil`.
`componentStyles` FieldStyle?	The container layout and appearance. Defaults to `nil`. Properties: `color`, `font`, `fontWeight`, `fontSize`, `labelFont`, `labelColor`, `valueFont`, `valueColor`, `backgroundColor`, `borderColor`, `borderWidth`, `cornerRadius`, `padding`, `margin`, `textAlignment`, `opacity`, `shadow` (ShadowStyle), `icon` (IconStyle), `labelSpacing`.
`inputStyles` FieldInputStateStyles?	The input field styling for different states. Defaults to `nil`. States: `base` (default unfocused), `active` (focused), `valid` (has valid value), `invalid` (has invalid value). Each state supports: `color`, `placeholderColor`, `fontWeight`, `fontSize`, `backgroundColor`, `borderColor`, `borderWidth`, `cornerRadius`, `padding`, `minHeight`.
`labelStyles` FieldLabelStateStyles?	The label styling by state. Defaults to `nil`. States: `base` (default), `active` (focused), `valid` (has valid value), `invalid` (has invalid value). Each state supports: `color`, `font`. Additional property: `minWidth` (CGFloat? - default: 80).
`labelPosition` LabelPosition?	The position of the label relative to the input. Options: `above`, `below`, `left`, `right`. Defaults to `nil`.
`invalidTextStyle` FieldMessageStyle?	The error message styling. Defaults to `nil`. Properties: `color`, `font`.
`invalidTextPosition` TextPosition?	The position of error text relative to the input. Defaults to `nil`.
`guideTextStyle` FieldMessageStyle?	The guide text styling. Defaults to `nil`. Properties: `color`, `font`.
`invalidIcon` Image?	The custom invalid state icon. Defaults to `nil`.
`validIcon` Image?	The custom valid state icon. Defaults to `nil`.
`displayValidIcon` Bool	Whether to show the valid icon. Defaults to `false`.
`displayInvalidIcon` Bool	Whether to show the invalid icon. Defaults to `true`.
`tooltipAccessibilityLabel` String?	The accessibility label for tooltip. Defaults to `nil`.
`displayRequiredIcon` Bool?	Whether to display the required indicator. Defaults to `nil`.
`allowToCopyPaste` Bool	Whether to allow copy and paste. Defaults to `true`.
`validationOnBlur` Bool	Whether to validate when the field loses focus. Defaults to `true`.
`validationOnChange` Bool	Whether to validate on each change. Defaults to `false`.
`isDisabled` Bool	Whether the field is disabled. Defaults to `false`.

Use this component on its own for a single line, or inside the pre-built Billing address form alongside country and postcode.

Styling

You can customise the appearance of the address field by providing custom styles:

config.inputStyles = FieldInputStateStyles(
    base: FieldInputStyle(
        fontSize: 16,
        backgroundColor: Color(.secondarySystemBackground),
        borderColor: Color(.separator),
        borderWidth: 1,
        cornerRadius: 8,
        padding: EdgeInsets(top: 12, leading: 12, bottom: 12, trailing: 12)
    ),
    active: FieldInputStyle(borderColor: .accentColor, borderWidth: 2),
    invalid: FieldInputStyle(borderColor: .red, borderWidth: 1)
)

config.labelStyles = FieldLabelStateStyles(
    base: FieldLabelStyle(color: .primary, font: .subheadline.weight(.semibold))
)

Event handling

The address component provides event handlers for user interaction and validation:

Callback	Description
`onChange: (() -> Void)?`	Called when the field value changes.
`onFocus: (() -> Void)?`	Called when the field gains focus.
`onBlur: (() -> Void)?`	Called when the field loses focus.
`onValidationPassed: (([ValidationResult]) -> Void)?`	Called when all validation checks pass. Receives an array of validation results.
`onValidationFailed: (([ValidationResult]) -> Void)?`	Called when validation fails. Receives an array of validation results containing error details.

For more information about event patterns, see Events.

Validation

The address component validates user input against the following rules:

Code	Condition	Default message
AD01	Field is empty	"Please enter street"
AD02	Value exceeds 100 characters	"The street exceeded maximum length"

Validation triggers based on your configuration (validationOnBlur, validationOnChange). Override default messages using the validations property.

Methods

`buildContent()`

Returns SwiftUI content for the address field:

address.buildContent()

Examples

Standalone field

A simple address field with custom label and placeholder:

let cfg = AddressComponentConfig(label: "Address", placeholder: "Enter address")
let address = try pxpCheckout.create(.address, componentConfig: cfg) as! AddressComponent

// In SwiftUI:
address.buildContent()

With custom messages and callbacks

Configure custom validation messages and event handlers:

var config = AddressComponentConfig(
    label: "Delivery address",
    validations: AddressValidationResource(
        AD01: "Street address is required",
        AD02: "Please shorten your address"
    )
)
config.onValidationFailed = { results in
    // Handle validation failure
}
let address = try pxpCheckout.create(.address, componentConfig: config) as! AddressComponent

For AVS with Card submit, pass a BillingAddressComponent or standalone country, postcode, and address components via billingAddressComponents. See Data validation for validation behaviour.