Postcode

Learn how to configure the postcode component.

Basic usage

Minimal configuration

The postcode component captures postal or ZIP codes. At minimum, you can create it with a label:

import SwiftUI
import PXPCheckoutSDK

let config = PostcodeComponentConfig(
    label: "Postcode",
    placeholder: "Enter postcode"
)

let postcode = try pxpCheckout.create(.postcode, componentConfig: config) as! PostcodeComponent

postcode.buildContent()

The postcode field allows alphanumeric characters, spaces, and hyphens. Other characters are stripped. Values are trimmed and capped at 10 characters.

Advanced configuration

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

var config = PostcodeComponentConfig(
    label: "ZIP / Postcode",
    placeholder: "e.g. SW1A 1AA",
    guideText: "Use the format for your region",
    validations: PostcodeValidationResource(
        PC01: "Enter a postcode",
        PC02: "Postcode is too long"
    ),
    onValidationFailed: { results in }
)

config.componentStyles = FieldStyle(cornerRadius: 8)
config.displayValidIcon = true
config.validationOnChange = true

let postcode = try pxpCheckout.create(.postcode, componentConfig: config) as! PostcodeComponent

Configuration

You can customise validation messages and field behaviour:

Property	Description
`validations` PostcodeValidationResource?	The custom validation error messages. Overrides SDK default messages for PC01 and PC02 error codes. Defaults to SDK localisation.
`label` String?	The field label text. 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 VoiceOver accessibility label. Defaults to `nil`.
`isRequired` Bool	Whether the field is required. For the postcode component, this is always `true` and can't be changed. Validation fails if the field is empty.
`componentStyles` FieldStyle?	The container styling. 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 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 label position relative to input. Options: `above`, `below`, `left`, `right`. Defaults to `nil`.
`invalidTextStyle` FieldMessageStyle?	The error text styling. Defaults to `nil`. Properties: `color`, `font`.
`invalidTextPosition` TextPosition?	The error message placement. Defaults to `nil`.
`guideTextStyle` FieldMessageStyle?	The guide text styling. Defaults to `nil`. Properties: `color`, `font`.
`invalidIcon` Image?	The custom error icon. Defaults to `nil`.
`validIcon` Image?	The custom valid icon. Defaults to `nil`.
`displayValidIcon` Bool	Whether to display the valid icon. Defaults to `false`.
`displayInvalidIcon` Bool	Whether to display the error icon. Defaults to `true`.
`tooltipAccessibilityLabel` String?	The tooltip accessibility label. 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 as the user types. Defaults to `false`.
`isDisabled` Bool	Whether the field is disabled. Defaults to `false`.

Validation messages

You can override default validation error messages:

`PostcodeValidationResource`

Property	Description
`PC01` String	Required. The message displayed when the field is empty but required.
`PC02` String	Required. The message displayed when the postcode exceeds 10 characters.

Event handling

Configure callbacks to respond to field events:

Property	Description
`onChange` (() -> Void)?	Called when the postcode value changes. Triggered as the user types or when the value is set programmatically. Defaults to `nil`.
`onFocus` (() -> Void)?	Called when the field gains focus. Triggered when the user taps into the field. Defaults to `nil`.
`onBlur` (() -> Void)?	Called when the field loses focus. Triggered when the user taps outside the field or moves to another field. Defaults to `nil`.
`onValidationPassed` (([ValidationResult]) -> Void)?	Called when validation passes. Receives an array of validation results. Defaults to `nil`.
`onValidationFailed` (([ValidationResult]) -> Void)?	Called when validation fails. Receives an array of validation results containing error details. Defaults to `nil`.

For more information about event patterns, see Events.

Validation

The postcode field validates input against the following rules:

Code	Condition	Default message
PC01	The field is empty but required	"Please enter postcode"
PC02	The postcode exceeds 10 characters	"The postcode exceeded maximum length"

The SDK automatically strips non-alphanumeric characters (except spaces and hyphens), trims whitespace, and enforces the 10-character maximum. Validation triggers based on your configuration (validationOnBlur, validationOnChange). Override default messages using the validations property.

Methods

`buildContent()`

Returns SwiftUI content for the postcode field:

postcode.buildContent()

Examples

Basic postcode field

A simple postcode field with default settings:

let config = PostcodeComponentConfig(label: "Postcode")
let postcode = try pxpCheckout.create(.postcode, componentConfig: config) as! PostcodeComponent

With custom styling

Apply custom styling to the field:

var config = PostcodeComponentConfig(label: "Postal code")
config.inputStyles = FieldInputStateStyles(
    base: FieldInputStyle(
        cornerRadius: 6,
        borderWidth: 1,
        borderColor: Color(.separator)
    ),
    active: FieldInputStyle(
        borderColor: .accentColor,
        borderWidth: 2
    )
)
config.displayValidIcon = true
let postcode = try pxpCheckout.create(.postcode, componentConfig: config) as! PostcodeComponent

With validation callbacks

Handle validation events:

var config = PostcodeComponentConfig(label: "Postcode")
config.onValidationPassed = { results in
    print("Postcode is valid")
}
config.onValidationFailed = { results in
    print("Postcode validation failed")
}
config.validationOnChange = true
let postcode = try pxpCheckout.create(.postcode, componentConfig: config) as! PostcodeComponent

With custom error messages

Override default validation messages:

let config = PostcodeComponentConfig(
    label: "Postcode",
    validations: PostcodeValidationResource(
        PC01: "Please enter your postcode",
        PC02: "Postcode must be 10 characters or less"
    )
)
let postcode = try pxpCheckout.create(.postcode, componentConfig: config) as! PostcodeComponent

Inside billing address

The postcode component is typically used inside the billing address component:

var postcodeConfig = PostcodeComponentConfig(
    label: "Postcode",
    placeholder: "Enter postcode"
)

let config = BillingAddressComponentConfig(
    fields: BillingAddressComponentFields(
        postcode: postcodeConfig
    )
)

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

With pre-fill from shipping

The postcode field works with the pre-fill billing address checkbox. When the checkbox is enabled, it copies the shipping postcode into this field:

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)
let billing = try pxpCheckout.create(.billingAddress, componentConfig: BillingAddressComponentConfig()) as! BillingAddressComponent

For billing address integration, see Billing address and Pre-fill billing address checkbox. For AVS and submit workflows, see Card submit.