Available from v1.8.0
InputAmount
InputAmount is a modern input field component for monetary amounts that displays currency symbols or ISO codes alongside the amount input. The component has built-in formatting, validation, and error handling capabilities.
Platform availability: iOS 17.0+
It includes the following features:
- A title label (optional).
- An input field with integrated currency display.
- An inline error view (shown when validation fails).
- Automatic formatting applied when the user dismisses the keyboard.
When to use:
- Use InputAmount when users need to enter monetary values with currency formatting, validation, and error handling.
- Consider using TextInput for general text input that doesn't require currency-specific formatting.
Note: When the user dismisses the keyboard after inputting an amount, formatting is automatically applied based on your configuration. Formatting never appears while the component is focused (i.e., while the user is actively editing).
Import
import BackbaseDesignSystem
Visual reference
|
Custom |
API reference
InputAmount
Properties
|
Property |
Type |
Description |
|---|---|---|
|
amount |
Decimal? |
The current input amount value |
|
amountTextField |
UITextField |
The underlying UITextField for direct access |
|
contentView |
UIView |
The container view for all content |
|
cornerRadius |
CGFloat |
The corner radius of the input field |
|
currency |
String |
The currency symbol/code string shown next to the amount |
|
currencyCode |
String |
The ISO 4217 currency code (e.g., "USD", "EUR") |
|
currencyLabel |
UILabel |
The label displaying the currency symbol/code |
|
currencySpacing |
CGFloat |
The space between currency label and amount input. Defaults to DesignSystem.shared.spacer.xxs |
|
errorTextColor |
UIColor |
The color of input field and currency label when showing an error |
|
inlineErrorView |
UIView |
The error view displayed below the input field |
|
inputField |
TextInput |
The TextInput component containing the text field |
|
inputFieldPaddings |
UIEdgeInsets |
The insets from the sides of the input field |
|
isIso |
Bool |
Whether to show currency as ISO code (e.g., "USD") instead of symbol (e.g., "$") |
|
isUnderlined |
Bool |
Whether to show/hide underline below input field. Defaults to false |
|
minimumAmountErrorMessage |
String |
The error message shown when minimum amount is not met |
|
normalTextColor |
UIColor |
The color of input field and currency label when amount is entered |
|
placeholder |
String |
The placeholder text shown when empty. Defaults to "0" |
|
placeholderColor |
UIColor |
The color of placeholder text and currency label when empty |
|
shouldUpdateAmountWhileEditing |
Bool |
Whether to update amount property while editing. Defaults to false |
|
textAlignment |
NSTextAlignment |
The alignment of title label, currency label, and input field |
|
titleLabel |
UILabel |
The label shown above the input field |
|
underlineView |
UIView |
The separator view shown when isUnderlined is true |
Callbacks
|
Callback |
Type |
Description |
|---|---|---|
|
inputTextDidChange |
((UITextField) -> Void)? |
The callback triggered when text changes |
|
inputTextDidBeginEditing |
((UITextField) -> Void)? |
The callback triggered when editing begins |
|
inputTextDidEndEditing |
((UITextField) -> Void)? |
The callback triggered when editing ends |
Initializers
- init(formattingOptions:)
|
Parameter |
Type |
Description |
|---|---|---|
|
formattingOptions |
DesignSystem.Formatting.Options |
Formatting options for the input. Defaults to DesignSystem.shared.formatting.defaultFormattingOptions.inputAmount |
Methods
setTitle(_:)
Sets the title label text.
|
Parameter |
Type |
Description |
|---|---|---|
|
title |
String |
The title text to display |
setText(_:)
Sets the text programmatically (must be valid or empty).
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
String |
The text value to set |
setErrorMessage(_:icon:)
Sets and displays an error message.
|
Parameter |
Type |
Description |
|---|---|---|
|
errorMessage |
String |
The error message to display |
|
icon |
UIImage? |
Optional icon to display with the error |
clearError()
Clears the error message and restores normal styling.
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
currencyCode |
String |
"" |
|
placeholder |
String |
"0" |
|
shouldUpdateAmountWhileEditing |
Bool |
false |
|
isUnderlined |
Bool |
false |
currencyCode
The currencyCode specifies the ISO 4217 currency code used for formatting and display.
let amountInput = InputAmount()
amountInput.currencyCode = "EUR"
shouldUpdateAmountWhileEditing
The shouldUpdateAmountWhileEditing controls when the amount property updates. When set to false, the amount property only updates when text field editing is finished. When set to true, the amount property updates in real-time as the user types.
var options = DesignSystem.Formatting.Options()
// Set locale (defaults to DesignSystem.Formatting.defaultLocaleForCurrencySymbol)
options.locale = Locale(identifier: "en_US")
// Choose between currency symbol or ISO code
options.formattingStyle = .currencyISOCode // or .currency
// Show plus sign for positive amounts
options.showsPlusSign = true
// Custom currency symbol
options.customSymbol = "€"
// Custom currency code
options.customCode = "EUR"
// Fraction digits
options.enableCustomFractions = true
options.minFractionDigits = 2
options.maxFractionDigits = 2
// Abbreviation for large amounts (e.g., $1.2k instead of $1,200)
options.abbreviator = DesignSystem.shared.formatting.abbreviators.default
let amountInput = InputAmount(formattingOptions: options)
Formatting options
The InputAmount component uses the NumberFormatting protocol to handle all formatting logic. Customize formatting behavior through DesignSystem.Formatting.Options:
undefined
Usage
Basic usage
let amountInput = InputAmount()
amountInput.setTitle("Amount")
amountInput.currencyCode = "USD"
amountInput.placeholder = "0.00"
view.addSubview(amountInput)
With custom formatting
var options = DesignSystem.Formatting.Options()
options.formattingStyle = .currencyISOCode
options.showsPlusSign = true
options.abbreviator = DesignSystem.shared.formatting.abbreviators.default
let amountInput = InputAmount(formattingOptions: options)
amountInput.setTitle("Transfer Amount")
amountInput.currencyCode = "EUR"
amountInput.shouldUpdateAmountWhileEditing = true
amountInput.inputTextDidChange = { textField in
if let amount = amountInput.amount {
print("Current amount: \(amount)")
}
}
Custom currency alignment
let amountInput = InputAmount()
amountInput.currencyAlignment = .trailing
Custom formatter
For advanced use cases, implement a custom formatter conforming to NumberFormatting:
class CustomAmountFormatter: NumberFormatting {
func format(amount: Decimal, options: DesignSystem.Formatting.Options) -> String? {
// Custom formatting logic
}
func inputAmountFormat(parameters: InputAmountFormatParameters) -> InputAmountFormatOutput {
// Custom input formatting logic
}
}
let customFormatter = CustomAmountFormatter()
DesignSystem.shared.formatting.amountFormatter = customFormatter
States and variants
Styles
InputAmount supports three visual styles: default, bordered, and underlined.
let inputView = InputAmount()
// Apply styles
DesignSystem.shared.styles.inputAmount(inputView) // default
DesignSystem.shared.styles.inputAmountBordered(inputView) // bordered
DesignSystem.shared.styles.inputAmountUnderlined(inputView) // underlined
Error state
The error state is displayed when validation fails or when manually setting an error message.
let amountInput = InputAmount()
let errorIcon = DesignSystem.Assets.icErrorOutline
amountInput.setErrorMessage("Amount must be at least $10.00", icon: errorIcon)
Customization
Styling
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.inputAmount |
Default input amount style |
|
DesignSystem.shared.styles.inputAmountBordered |
Bordered input amount style |
|
DesignSystem.shared.styles.inputAmountUnderlined |
Underlined input amount style |
Overriding decimal places
Override the number of decimal places globally for specific currencies:
DesignSystem.shared.formatting.numberOfDecimalsForCurrencyOverride = { currencyCode, locale in
if currencyCode == "COP" {
return 2
}
return nil
}
Global 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).
Error handling
Set and clear errors manually:
let amountInput = InputAmount()
// Show error
let errorIcon = DesignSystem.Assets.icErrorOutline
amountInput.setErrorMessage("Amount must be at least $10.00", icon: errorIcon)
// Clear error
amountInput.clearError()
Events
|
Event |
Type |
Description |
|---|---|---|
|
inputTextDidChange |
((UITextField) -> Void)? |
Called when the text changes |
|
inputTextDidBeginEditing |
((UITextField) -> Void)? |
Called when editing begins |
|
inputTextDidEndEditing |
((UITextField) -> Void)? |
Called when editing ends |
let amountInput = InputAmount()
amountInput.inputTextDidChange = { textField in
print("Text changed: \(textField.text ?? "")")
}
amountInput.inputTextDidBeginEditing = { textField in
print("Editing began")
}
amountInput.inputTextDidEndEditing = { textField in
print("Editing ended")
}
Accessibility
The InputAmount component supports accessibility features for users with visual impairments and assistive technologies.
Accessibility configuration
|
Property |
Description |
Type |
|---|---|---|
|
accessibilityLabel |
The accessible label for the amount input |
String |
|
accessibilityHint |
The accessible hint describing the input purpose |
String |
Best practices
- Set a descriptive accessibilityLabel that includes the currency context.
- Use accessibilityHint to explain the expected input format.
- Ensure error messages are announced via VoiceOver.
let amountInput = InputAmount()
amountInput.amountTextField.accessibilityLabel = "Transfer amount in US dollars"
amountInput.amountTextField.accessibilityHint = "Enter the amount you want to transfer"
Dependencies
- External dependencies: None
- Internal dependencies:
- TextInput: Base text input component
- NumberFormatting: Protocol for amount formatting
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/[state]: Color tokens for default, focused, error, and disabled states
Default state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.input-amount.default.background |
{theme.color.background.surface-1} |
|
Border |
theme.color.input-amount.default.border |
{theme.color.border.default} |
|
Value |
theme.color.input-amount.default.value |
{theme.color.foreground.default} |
Focused state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.input-amount.focused.background |
{theme.color.background.surface-1} |
|
Border |
theme.color.input-amount.focused.border |
{theme.color.border.brand} |
|
Value |
theme.color.input-amount.focused.value |
{theme.color.foreground.default} |
Error state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.input-amount.error.background |
{theme.color.background.surface-1} |
|
Border |
theme.color.input-amount.error.border |
{theme.color.border.danger} |
|
Value |
theme.color.input-amount.error.value |
{theme.color.foreground.default} |
Disabled state tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.input-amount.disabled.background |
{theme.color.background.disabled} |
|
Border |
theme.color.input-amount.disabled.border |
{theme.color.border.disabled} |
|
Value |
theme.color.input-amount.disabled.value |
{theme.color.foreground.disabled} |
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 |
|---|---|---|
|
Typography |
DesignSystem.shared.fonts.preferredFont(.body, .regular) |
Input text font |
|
Spacing |
DesignSystem.shared.spacer.xxs |
Currency spacing |
|
Default Style |
DesignSystem.shared.styles.inputAmount |
Default input amount style |
|
Bordered Style |
DesignSystem.shared.styles.inputAmountBordered |
Bordered input amount style |
|
Underlined Style |
DesignSystem.shared.styles.inputAmountUnderlined |
Underlined input amount style |
|
Formatting |
DesignSystem.shared.formatting.defaultFormattingOptions.inputAmount |
Default formatting options |
Localization
Override the following strings to customize the text for InputAmount on the app level:
"DesignSystem.inputAmount.minimumAmountErrorMessage" = "Minimum amount not met";
See also
- NumberFormatting - Protocol for customizing formatting behavior
- TextInput - Single-line text input component