Available from v8.0.0
BB.InputAmount
A SwiftUI view that displays an amount input field with currency formatting and validation.
Platform availability: iOS 17.0+
When to use:
- Use BB.InputAmount when collecting monetary values from users, such as transfer amounts, payment values, or budget entries.
- Consider BB.InputText when the input is not specifically a currency amount or doesn't require currency formatting.
Import
import BackbaseDesignSystem
import SwiftUI
Visual reference
Default |
Error |
Disabled |
ISO Code |
Readonly |
Currency Selector |
|
|
Currency Selector Page
|
|
API reference
BB.InputAmount
BB.InputAmount is a standardized monetary input component for SwiftUI applications. It supports various currency formats, validation states, and helper text, with built-in currency formatting based on the specified currency code. The locale used for currency formatting is controlled by DesignSystem.Formatting.defaultLocaleForCurrencySymbol, which defaults to the system's current locale.
Enumerations
Layout
Defines the visual style of the amount input field.
|
Case |
Description |
|---|---|
|
default |
Standard bordered container with rounded corners |
|
prominent |
Underlined style with prominent bottom border when focused |
CurrencyDisplay
Controls how the currency is displayed.
|
Case |
Description |
|---|---|
|
symbol |
Shows currency symbol (e.g., "$" for USD) |
|
isoCode |
Shows ISO currency code (e.g., "USD") |
|
custom |
Uses a custom formatter for currency display |
Methods
errorText(_:)
Sets the error text using a binding.
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
Binding<String?> |
Binding to the error message to display |
Returns: Self - A modified version of the input with error text.
helperText(_:)
Sets the helper text.
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
String? |
Helper text to display below the input |
Returns: Self - A modified version of the input with helper text.
helperText(_:) (Binding)
Sets the helper text using a binding.
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
Binding<String?> |
Binding to the helper text |
Returns: Self - A modified version of the input with helper text.
readOnly(_:)
Sets the read-only state.
|
Parameter |
Type |
Description |
|---|---|---|
|
isReadOnly |
Bool |
Whether the input is read-only |
Returns: Self - A modified version of the input with read-only state.
readOnly(_:) (Binding)
Sets the read-only state using a binding.
|
Parameter |
Type |
Description |
|---|---|---|
|
isReadOnly |
Binding<Bool> |
Binding to the read-only state |
Returns: Self - A modified version of the input with read-only state.
keyboardType(_:)
Sets the keyboard type for the amount input.
|
Parameter |
Type |
Default |
Description |
|---|---|---|---|
|
type |
UIKeyboardType |
.decimalPad |
The keyboard type to use |
Returns: Self - A modified version of the input with the keyboard type.
currencySelector(onTap:)
Adds a currency selector button next to the amount input field.
|
Parameter |
Type |
Description |
|---|---|---|
|
onTap |
(() -> Void)? |
Callback when the currency selector is tapped |
Returns: Self - A modified version of the input with currency selector.
currencyDisplay(_:)
Sets the currency display format.
|
Parameter |
Type |
Description |
|---|---|---|
|
display |
CurrencyDisplay |
How to display the currency |
Returns: Self - A modified version of the input with currency display.
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
amount |
Binding<Decimal?> |
— |
|
currencyCode |
String or Binding<String> |
— |
|
placeholder |
String |
"0.00" |
|
layout |
Layout |
.default |
|
labelPrimaryText |
String? |
nil |
|
labelSecondaryText |
String? |
nil |
amount
The amount property binds to the decimal value entered by the user. This is a required parameter for the initializer.
@State private var amount: Decimal?
BB.InputAmount(amount: $amount, currencyCode: "USD")
currencyCode
The currencyCode property specifies the ISO 4217 currency code for formatting. Can be a static string or a binding.
BB.InputAmount(amount: $amount, currencyCode: "EUR")
// Or with binding for dynamic currency selection
BB.InputAmount(amount: $amount, currencyCode: $selectedCurrency)
layout
The layout property controls the visual style of the input field.
BB.InputAmount(amount: $amount,
currencyCode: "USD",
layout: .prominent)
Usage
Basic usage
Create a simple amount input field.
import SwiftUI
import BackbaseDesignSystem
@State private var amount: Decimal?
var body: some View {
BB.InputAmount(amount: $amount,
currencyCode: "USD")
}
Common use cases
Transfer amount with validation
@State private var amount: Decimal?
@State private var errorMessage: String? = "Invalid amount"
@State private var isReadOnly = false
var body: some View {
BB.InputAmount(amount: $amount,
currencyCode: "EUR",
placeholder: "0.00",
layout: .prominent,
labelPrimaryText: "Transfer Amount",
labelSecondaryText: "Maximum transfer: €10,000")
.currencyDisplay(.isoCode)
.errorText($errorMessage)
.helperText("Please enter an amount between €1 and €10,000")
.readOnly(isReadOnly)
.keyboardType(.decimalPad)
}
Custom currency display
@State private var amount: Decimal?
var body: some View {
BB.InputAmount(amount: $amount,
currencyCode: "USD")
.currencyDisplay(.custom { currencyCode, locale in
"\(currencyCode) "
})
}
Using currency selector
@State private var amount: Decimal?
@State private var currencyCode: String = "USD"
@State private var showCurrencyPicker = false
var body: some View {
BB.InputAmount(amount: $amount,
currencyCode: $currencyCode,
placeholder: "0.00",
labelPrimaryText: "Transfer Amount")
.currencySelector(onTap: {
showCurrencyPicker = true
})
.sheet(isPresented: $showCurrencyPicker) {
CurrencyPickerView(selectedCurrency: $currencyCode)
}
}
Advanced usage
Configuring locale
The locale used for currency formatting can be configured:
DesignSystem.Formatting.defaultLocaleForCurrencySymbol = Locale(identifier: "en_US")
Or set the InputAmountValidator object with a locale:
DesignSystem.shared.formatting.inputAmountValidators.default = InputAmountValidator(locale: .init(identifier: "fr_FR"))
By default, the locale is set to .autoupdatingCurrent, which means it will automatically update based on the system's current locale settings.
Configuring formatting options
All inputs by default are initialized with the DesignSystem.shared.formatting.defaultFormattingOptions.inputAmount object and can be customized to affect all InputAmount components (UIKit and SwiftUI).
Note: Not all formatting option properties affect the InputAmount. Some are used for formatting AmountText only.
States and variants
Layout variants
Default layout
Standard bordered container with rounded corners.
BB.InputAmount(amount: $amount,
currencyCode: "USD",
layout: .default)
Prominent layout
Underlined style with prominent bottom border when focused.
BB.InputAmount(amount: $amount,
currencyCode: "USD",
layout: .prominent)
States
Normal state
The default state when the input is interactive.
Visual characteristics:
- Default border color
- Placeholder text visible when empty
- Currency symbol or code displayed
Focused state
Active when the input field has keyboard focus.
Visual characteristics:
- Brand-colored border
- Cursor visible in the input field
Error state
Displayed when validation fails or an error message is set.
Visual characteristics:
- Danger-colored border
- Error icon displayed
- Error text shown below the input
Disabled state
Applied when the input is not interactive.
Visual characteristics:
- Disabled border and text colors
- User interaction blocked
Read-only state
Applied when the input displays an amount but does not accept changes.
Visual characteristics:
- Content is visible but not editable
Customization
Currency display options
Configure how the currency is shown.
// Symbol (e.g., "$")
BB.InputAmount(amount: $amount, currencyCode: "USD")
.currencyDisplay(.symbol)
// ISO code (e.g., "USD")
BB.InputAmount(amount: $amount, currencyCode: "USD")
.currencyDisplay(.isoCode)
// Custom formatter
BB.InputAmount(amount: $amount, currencyCode: "USD")
.currencyDisplay(.custom { code, locale in "\(code): " })
Currency selector
Add a currency selector button for multi-currency support.
BB.InputAmount(amount: $amount, currencyCode: $currency)
.currencySelector(onTap: { showPicker = true })
Accessibility
This component can be configured with accessibility features at the integration level. Use the standard SwiftUI accessibility modifiers to ensure a fully accessible experience for all users.
Accessibility configuration
|
Modifier |
Description |
|---|---|
|
.accessibilityLabel(_:) |
Sets the accessibility label for screen readers |
|
.accessibilityHint(_:) |
Provides additional context for the action |
|
.accessibilityValue(_:) |
Sets the current value for the element |
Best practices
- Provide meaningful accessibility labels that describe the element's purpose.
- Use accessibility hints to provide additional context when needed.
- Ensure all interactive elements are accessible.
BB.InputAmount()
.accessibilityLabel("Descriptive label")
.accessibilityHint("Additional context")
Dependencies
- External dependencies: None
- Internal dependencies: BackbaseDesignSystem
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 InputAmount:
- color/input-amount/default: Default state background, border, placeholder, and value colors
- color/input-amount/focused: Focused state colors
- color/input-amount/error: Error state colors
- color/input-amount/disabled: Disabled state colors
- color/input-amount/read-only: Read-only state colors
Default state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.input-amount.default.background |
{theme.color.background.none} |
|
Border |
theme.color.input-amount.default.border |
{theme.color.input.default.border} |
|
Placeholder |
theme.color.input-amount.default.placeholder |
{theme.color.input.default.placeholder} |
|
Value |
theme.color.input-amount.default.value |
{theme.color.input.default.value} |
Focused state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Border |
theme.color.input-amount.focused.border |
{theme.color.input.focused.border} |
Error state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Border |
theme.color.input-amount.error.border |
{theme.color.input.error.border} |
Dimension tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Corner Radius |
theme.radius.input-amount.default |
8 |
|
Height |
theme.height.input-amount.default |
56 |
|
Padding X |
theme.padding-x.input-amount.default |
16 |
|
Padding Y |
theme.padding-y.input-amount.default |
2 |
|
Border Width |
theme.border-width.input-amount.default |
1 |
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Default Border |
Theme.colors.border.default |
Default input border color |
|
Focused Border |
Theme.colors.border.brand |
Border color when focused |
|
Error Border |
Theme.colors.border.danger |
Border color in error state |
|
Placeholder |
Theme.colors.foreground.support |
Placeholder text color |
|
Value |
Theme.colors.foreground.default |
Input value text color |
|
Label |
Theme.colors.foreground.default |
Label text color |
Localization
The following strings are available for localization:
|
Key |
Default Value |
Description |
|---|---|---|
|
DesignSystem.inputAmount.accessibility.textFieldLabel |
"Amount input" |
Accessibility label for the input |
|
DesignSystem.inputAmount.accessibility.textFieldValue |
"%1$@%2$@" |
Format for currency and amount |
|
DesignSystem.inputAmount.accessibility.errorIcon |
"Error icon" |
Accessibility label for error icon |
To customize these strings, add the keys to your app's Localizable.strings file.
See also
- BB.InputText - Text input field component
- BB.InputDate - Date input field component
- BB.InputPassword - Password input field component