Available from v1.0.0
Amount
Amount is a locale-aware formatting utility for displaying monetary values with currency symbols, signs, and abbreviations.
Platform availability: iOS 17.0+
When to use:
- Use Amount formatting when displaying monetary values that need proper locale, currency, and sign formatting.
- Consider custom implementation when you need simple number formatting without currency-specific features.
It includes the following features:
- Locale-aware currency formatting.
- Configurable positive and negative sign display.
- Sign-based text highlighting.
- Amount abbreviation support (e.g., 1.2k).
- Custom accessibility label formatting.
Import
import BackbaseDesignSystem
Visual reference
Colored |
Custom |
Locale |
Long |
Minus sign |
Plus sign |
|
|
|
|
API reference
DesignSystem.Formatting
The formatting API for amount display.
Methods
formatAmountLabel(amount:options:accessibilityOptions:label:)
Formats and applies an amount to a UILabel.
|
Parameter |
Type |
Description |
|---|---|---|
|
amount |
Decimal |
The numerical value to display |
|
options |
DesignSystem.Formatting.Options |
Formatting options for display |
|
accessibilityOptions |
DesignSystem.Formatting.Options? |
Formatting options for accessibility label. Pass nil to use options |
|
label |
UILabel |
The label for displaying the amount |
makeFormatter()
- Creates a new amount formatter instance.
- Returns: AmountFormatter - A formatter for converting amounts to strings
DesignSystem.Formatting.Options
Configuration options for amount formatting.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
locale |
Locale |
The locale for formatting |
|
formattingStyle |
FormattingStyle |
The formatting type (currency, ISO, decimal, etc.) |
|
showsPlusSign |
Bool |
Whether to show + sign for positive amounts |
|
enableSignHighlighting |
Bool |
Enable text highlighting based on sign |
|
minFractionDigits |
Int |
Minimum fraction digits |
|
maxFractionDigits |
Int |
Maximum fraction digits |
|
enableCustomFractions |
Bool |
Override default currency decimal fractions |
|
currencyCode |
String? |
Custom currency code |
|
currencySymbol |
String? |
Custom currency symbol |
|
abbreviator |
AmountAbbreviator? |
Abbreviator for large amounts |
|
negativeFormat |
String? |
Custom format for negative amounts |
|
positiveFormat |
String? |
Custom format for positive amounts |
|
currencyGroupingSeparator |
String? |
Symbol for grouping (e.g., comma in 1,200) |
|
usesGroupingSeparator |
Bool |
Whether to use grouping separator |
|
multiplier |
NSNumber? |
Multiplier for the number formatter |
Usage
Basic usage
let options = DesignSystem.Formatting.Options(
locale: Locale(identifier: "en_US"),
formattingStyle: .currency
)
DesignSystem.shared.formatting.formatAmountLabel(
amount: 1200,
options: options,
label: myLabel
)
Formatting labels with sign highlighting
let options = DesignSystem.Formatting.Options(
locale: Locale(identifier: "en_US"),
formattingStyle: .currencyISOCode,
showsPlusSign: true,
enableSignHighlighting: true,
abbreviator: DesignSystem.shared.styles.abbreviators.default,
accessibility: .init(positiveFormat: "Incoming transaction %@", negativeFormat: "Outgoing transaction %@")
)
var accessibilityOptions = options
accessibilityOptions.showsPlusSign = false
accessibilityOptions.abbreviator = nil
DesignSystem.shared.formatting.formatAmountLabel(
amount: 1200,
options: options,
accessibilityOptions: accessibilityOptions,
label: myLabel
)
Formatting strings
let options = DesignSystem.Formatting.Options(
locale: Locale(identifier: "en_US"),
formattingStyle: .currencyISOCode,
showsPlusSign: true,
abbreviator: DesignSystem.shared.styles.abbreviators.default
)
let formatter = DesignSystem.Formatting.makeFormatter()
let formattedAmount = formatter.format(amount: 1200, options: options)
Accessibility
The Amount formatting utility is built with accessibility in mind. See the information below for supported behaviors and configuration options to ensure a fully accessible experience for all users.
Accessibility configuration
|
Property |
Type |
Description |
|---|---|---|
|
accessibility.positiveFormat |
String |
The format string for positive amount accessibility labels |
|
accessibility.negativeFormat |
String |
The format string for negative amount accessibility labels |
Default localized strings
By default, positive and negative amount accessibility labels use the following localized strings.
"DesignSystem.formatting.accessibility.positiveFormat" = "%@";
"DesignSystem.formatting.accessibility.negativeFormat" = "Negative %@";
Add these key/string pairs to your main localizable string file to override the defaults.
Best practices
- Use descriptive format strings that clearly indicate the transaction direction (e.g., "Credit of %@", "Debit of %@").
- Avoid abbreviations in accessibility labels for VoiceOver clarity.
- Test with VoiceOver to ensure amounts are read correctly in different locales.
Custom accessibility formats
let options = DesignSystem.Formatting.Options(
locale: Locale(identifier: "en_US"),
formattingStyle: .currency,
accessibility: .init(
positiveFormat: "Credit of %@",
negativeFormat: "Debit of %@"
)
)
Dependencies
- External dependencies: None
- Internal dependencies: DesignSystem.Formatting, DesignSystem.Styles.AmountAbbreviator
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
This utility uses semantic tokens only. Formatting behavior is controlled through DesignSystem.Formatting.Options rather than JSON token paths.
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Typography |
DesignSystem.shared.fonts.preferredFont() |
Text styling for amount display |
|
Colors |
Theme.colors.foreground.default |
Default text color for amounts |
|
Colors |
Theme.colors.foreground.success |
Positive amount highlight color |
|
Colors |
Theme.colors.foreground.danger |
Negative amount highlight color |
|
Abbreviators |
DesignSystem.shared.styles.abbreviators.default |
Amount abbreviation (e.g., 1.2k) |
|
Formatter |
DesignSystem.Formatting.makeFormatter() |
Creates amount formatter instance |
See also
- InputAmount - Amount input component
- ProductNumberFormatter - Product number formatting utility