Available from v2.5.0
AddressForm
AddressForm is a UIKit view controller component for entering or editing postal addresses with optional address autocomplete functionality.
Platform availability: iOS 17.0+
When to use:
- Use AddressForm when collecting structured postal address information with support for state/country selection and optional address autocomplete.
- Consider using individual TextInput fields when you need a custom address layout or when collecting partial address information.
It includes the following features:
- Input fields for up to nine address fields (five default, four extra).
- Configurable field order and visibility.
- Drop-down input for state/country sub-division selection.
- Optional address autocomplete screen with external service integration.
- Real-time form change callbacks for validation.
- Inline error display for field validation.
Import
import BackbaseDesignSystem
Visual reference
|
Plain |
Search |
Autocomplete |
API reference
AddressForm
A view controller that displays address input fields. This class should not be instantiated directly; use AddressFormFactory instead.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
address |
AddressFormValues? |
The address currently displayed on the form |
|
addressErrors |
AddressFormValues? |
Inline errors to display on the form fields |
|
onFormChange |
((AddressFormValues?) -> Void)? |
Callback triggered when form content changes |
AddressFormFactory
Factory for creating AddressForm instances with the provided configuration.
Methods
make(formConfiguration:address:
Creates an AddressForm without address autocomplete support.
|
Parameter |
Type |
Description |
|---|---|---|
|
formConfiguration |
AddressFormConfiguration |
Configuration object for the address form |
|
address |
AddressFormValues? |
Optional address to pre-populate the form |
Returns: AddressForm
make(formConfiguration:suggestionConfiguration:address:
Creates an AddressForm with address autocomplete support.
|
Parameter |
Type |
Description |
|---|---|---|
|
formConfiguration |
AddressFormConfiguration |
Configuration object for the address form |
|
suggestionConfiguration |
AddressSuggestionConfiguration |
Configuration for the autocomplete screen |
|
address |
AddressFormValues? |
Optional address to pre-populate the form |
Returns: AddressForm
AddressFormConfiguration
Configuration properties for the AddressForm.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
availableSubDivisions |
[(abbreviation: String?, name: String)] |
Available states/sub-divisions for selection |
|
visibleFields |
[AddressField] |
Fields to display and their order |
|
strings |
AddressFormConfiguration.Strings |
Localized strings for form labels |
AddressField
Enum describing input fields on the address form.
|
Case |
Description |
|---|---|
|
addressLine1 |
First line of the address |
|
addressLine2 |
Second line of the address |
|
city |
City, town, or municipality |
|
subDivision |
State or county (rendered as dropdown) |
|
zip |
ZIP or postal code |
|
extra1 |
Additional field 1 (hidden by default) |
|
extra2 |
Additional field 2 (hidden by default) |
|
extra3 |
Additional field 3 (hidden by default) |
|
extra4 |
Additional field 4 (hidden by default) |
|
compound(AddressField, AddressField) |
Two fields in a horizontal row |
AddressFormValues
Protocol representing a postal address.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
addressLine1 |
String |
First line of the address |
|
addressLine2 |
String |
Second line of the address |
|
city |
String |
City name |
|
subDivision |
String |
State or county |
|
zip |
String |
ZIP or postal code |
|
extraLine1 |
String |
Additional data (default: empty) |
|
extraLine2 |
String |
Additional data (default: empty) |
|
extraLine3 |
String |
Additional data (default: empty) |
|
extraLine4 |
String |
Additional data (default: empty) |
|
isEmpty |
Bool |
Returns true if all fields are empty |
AddressSuggestionConfiguration
Configuration for the address autocomplete screen.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
noConnectionStateViewConfiguration |
StateViewConfiguration |
Error state for no internet connection |
|
noResultsFoundStateViewConfiguration |
StateViewConfiguration |
Error state for no search results |
|
unknownErrorStateViewConfiguration |
StateViewConfiguration |
Error state for unknown errors |
|
strings |
AddressSuggestionConfiguration.Strings |
Localized strings for autocomplete screen |
Configuration
Strings configuration
The AddressFormConfiguration.Strings struct configures all form labels.
|
Property |
Type |
Description |
|---|---|---|
|
address1InputTitle |
String |
Title for address line 1 field |
|
address2InputTitle |
String |
Title for address line 2 field |
|
cityInputTitle |
String |
Title for city field |
|
subDivisionInputTitle |
String |
Title for state/sub-division field |
|
subDivisionInputPlaceholder |
String |
Placeholder for state field |
|
zipInputTitle |
String |
Title for ZIP code field |
|
extra1InputTitle |
String |
Title for extra field 1 |
|
extra2InputTitle |
String |
Title for extra field 2 |
|
extra3InputTitle |
String |
Title for extra field 3 |
|
extra4InputTitle |
String |
Title for extra field 4 |
|
searchInputPlaceholder |
String? |
Placeholder for search box |
Usage
Basic usage
The AddressForm component is a view controller intended to be used as a child view controller.
import BackbaseDesignSystem
private lazy var states = [
(abbreviation: "CA", name: "California"),
(abbreviation: "NY", name: "New York"),
(abbreviation: "TX", name: "Texas")
]
private lazy var formConfiguration: AddressFormConfiguration = {
.init(
strings: .init(
address1InputTitle: "Street address",
address2InputTitle: "Apartment or suite",
cityInputTitle: "City",
subDivisionInputTitle: "State",
subDivisionInputPlaceholder: "Select a state",
zipInputTitle: "ZIP Code"
),
availableSubDivisions: states
)
}()
private lazy var addressFormController: AddressForm = {
AddressFormFactory.make(formConfiguration: formConfiguration)
}()
override func viewDidLoad() {
super.viewDidLoad()
view.addSubview(addressFormController.view)
addChild(addressFormController)
addressFormController.didMove(toParent: self)
}
Custom field layout
Configure visible fields and their order using the visibleFields parameter. Use compound to place two fields in a single row.
struct MyAddress: AddressFormValues {
var addressLine1: String
var addressLine2: String
var city: String
var subDivision: String
var zip: String
}
let existingAddress = MyAddress(
addressLine1: "123 Main St",
addressLine2: "Apt 4B",
city: "San Francisco",
subDivision: "CA",
zip: "94102"
)
let addressFormController = AddressFormFactory.make(
formConfiguration: formConfiguration,
address: existingAddress
)
Address autocomplete
To use address autocomplete, implement AddressSearchResultsProvider and configure AddressSuggestionConfiguration.
class AddressService: AddressSearchResultsProvider {
func search(query: String, completion: @escaping (AddressAutocompleteResult) -> Void) {
// Implement search logic with external service
}
func searchApartments(
selection: AddressSuggestion,
query: String,
completion: @escaping AddressSuggestionCompletion
) {
// Implement secondary address search
}
}
let suggestionProvider = AddressService()
let suggestionConfiguration = AddressSuggestionConfiguration(
searchResultsProvider: suggestionProvider,
strings: .init(
addressNotFound: "Address not found? Enter manually",
searchBarPlaceholder: "Start typing your address"
)
)
let addressFormController = AddressFormFactory.make(
formConfiguration: formConfiguration,
suggestionConfiguration: suggestionConfiguration
)
Handling form changes
Use the onFormChange callback to perform real-time validation.
addressFormController.onFormChange = { address in
guard let address = address else { return }
// Perform validation
if address.zip.count < 5 {
// Handle validation error
}
}
Displaying validation errors
Set inline errors on specific fields using addressErrors.
struct AddressErrors: AddressFormValues {
var addressLine1 = ""
var addressLine2 = ""
var city = ""
var subDivision = ""
var zip = "ZIP code is required"
}
addressFormController.addressErrors = AddressErrors()
Customization
Styling
The following shared styles are used with the address form:
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.textInput |
Applied to all text input fields |
|
DesignSystem.shared.styles.searchInput |
Applied to the search box |
The following shared styles are used on the autocomplete screen:
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.searchBar |
Applied to the search bar |
|
DesignSystem.shared.styles.tableView |
Applied to the results table |
|
DesignSystem.shared.styles.tableViewCell |
Applied to result cells |
|
DesignSystem.shared.styles.tableViewLinkCell |
Applied to the manual entry link |
Events
|
Event |
Type |
Description |
|---|---|---|
|
onFormChange |
((AddressFormValues?) -> Void)? |
Triggered when any form field changes |
addressFormController.onFormChange = { address in print("Address changed: \(address?.addressLine1 ?? "")")}
Accessibility
The AddressForm component is built with accessibility in mind.
Accessibility configuration
|
Property |
Description |
|---|---|
|
accessibilityIdentifier |
Each input field has a unique identifier (e.g., addressForm.address1Input) |
|
accessibilityLabel |
Input fields use their title as the accessibility label |
|
textContentType |
Fields use appropriate content types for autofill support |
Text content types
|
Field |
Content Type |
|---|---|
|
Address Line 1 |
.streetAddressLine1 |
|
Address Line 2 |
.streetAddressLine2 |
|
City |
.addressCity |
|
State |
.addressState |
|
ZIP |
.postalCode |
Best practices
- Ensure all custom field labels are descriptive for VoiceOver users.
- Test the autocomplete flow with VoiceOver to verify navigation.
- Consider adding custom accessibility hints for complex field interactions.
Dependencies
- External dependencies: None
- Internal dependencies:
- TextInput: Used for all address input fields
- StateView: Used for error states on autocomplete screen
- NavigationController: Used for presenting autocomplete screen
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
Tokens are defined in defaultTokens.json, which is integrated in the bundle of the framework, and can be customized by providing your own theme JSON file.
Token groups used by AddressForm:
- color/input/[state]: Input field colors for different states (via TextInput component)
- color/search-input: Search box styling tokens
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Input Background |
theme.color.input.default.background |
{theme.color.background.surface-1} |
|
Input Border |
theme.color.input.default.border |
{theme.color.border.default} |
|
Input Border (focused) |
theme.color.input.focused.border |
{theme.color.border.brand} |
|
Input Border (error) |
theme.color.input.error.border |
{theme.color.border.danger} |
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Spacing |
DesignSystem.shared.spacer.md |
Medium spacing between form elements |
|
Text Input Style |
DesignSystem.shared.styles.textInput |
Applied to all text input fields |
|
Search Input Style |
DesignSystem.shared.styles.searchInput |
Applied to the search box |
|
Search Bar Style |
DesignSystem.shared.styles.searchBar |
Applied to autocomplete search bar |
|
Table View Style |
DesignSystem.shared.styles.tableView |
Applied to autocomplete results table |
|
Table Cell Style |
DesignSystem.shared.styles.tableViewCell |
Applied to result cells |
|
Link Cell Style |
DesignSystem.shared.styles.tableViewLinkCell |
Applied to manual entry link |
|
Icons |
DesignSystem.Assets.icExpandMore |
Dropdown expand icon |
See also
- TextInput - The input field component used within the form
- StateView - Error state display component
- AddressPreview - Component for displaying formatted addresses