Available from v8.0.0
BB.TextArea
A SwiftUI view that displays a multi-line text input area with customizable appearance and behavior.
Platform availability: iOS 17.0+
When to use:
- Use BB.TextArea when collecting longer-form text input such as comments, descriptions, or messages.
- Consider BB.InputText when you only need single-line text entry.
Import
import SwiftUI
import BackbaseDesignSystem
Visual reference
Default |
Error |
Disabled State |
API reference
BB.TextArea
BB.TextArea is a standardized multi-line text input component for SwiftUI applications. It supports various states including editing, focused, and error states, along with optional labels, character limits, and helper text.
Initializers
init(text:placeholder:labelPrimaryText:labelSecondaryText:characterLimit:)
Creates a new text area with the specified binding, labels, and optional character limit.
|
Parameter |
Type |
Default |
Description |
|---|---|---|---|
|
text |
Binding<String> |
— |
Binding to the text content |
|
placeholder |
String |
— |
Placeholder text shown when empty |
|
labelPrimaryText |
String |
— |
Primary label text above the text area |
|
labelSecondaryText |
String? |
nil |
Optional secondary label text |
|
characterLimit |
UInt |
500 |
Maximum character limit |
Methods
- helperText(_:)
- Sets the helper text displayed below the text area.
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
String? |
Helper text to display |
Returns: Self - A modified version of the text area with helper text.
- errorText(_:) (Binding)
- Sets the error text using a binding.
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
Binding<String?> |
Binding to the error text |
Returns: Self - A modified version of the text area with error state.
- errorText(_:)
- Sets the error text directly.
|
Parameter |
Type |
Description |
|---|---|---|
|
text |
String? |
Error text to display |
Returns: Self - A modified version of the text area with error state.
- readOnly(_:)
- Sets the read-only state of the text area.
|
Parameter |
Type |
Description |
|---|---|---|
|
isReadOnly |
Bool |
Whether the text area is read-only |
Returns: Self - A modified version of the text area with read-only state.
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
text |
Binding<String> |
— |
|
placeholder |
String |
— |
|
labelPrimaryText |
String |
— |
|
labelSecondaryText |
String? |
nil |
|
characterLimit |
UInt |
500 |
text
The text property binds to the string value entered by the user. This is a required parameter for the initializer.
@State private var messageText = ""
BB.TextArea(text: $messageText,
placeholder: "Enter message",
labelPrimaryText: "Message")
placeholder
The placeholder property displays hint text when the text area is empty.
BB.TextArea(text: $text,
placeholder: "Type your message here...",
labelPrimaryText: "Message")
labelPrimaryText
The labelPrimaryText property displays a primary label above the text area. This is a required parameter.
BB.TextArea(text: $text,
placeholder: "Enter description",
labelPrimaryText: "Description")
labelSecondaryText
The labelSecondaryText property displays secondary text next to the primary label.
BB.TextArea(text: $text,
placeholder: "Enter notes",
labelPrimaryText: "Notes",
labelSecondaryText: "(Optional)")
characterLimit
The characterLimit property sets the maximum number of characters the user can enter. Defaults to 500.
BB.TextArea(text: $text,
placeholder: "Enter bio",
labelPrimaryText: "Bio",
characterLimit: 250)
Usage
Basic usage
Create a simple text area with a label and placeholder.
import SwiftUI
import BackbaseDesignSystem
@State private var messageText = ""
var body: some View {
BB.TextArea(
text: $messageText,
placeholder: "Enter your message here...",
labelPrimaryText: "Message"
)
}
Common use cases
Text area with state controls
Use SwiftUI state controls to manage focus and disabled states.
@State var disabled = false
@FocusState var isFocused: Bool
var body: some View {
BB.TextArea(
text: $enteredText,
placeholder: "Enter your message here...",
labelPrimaryText: "Message"
)
.focused($isFocused)
.disabled(disabled)
}
Text area with validation
Configure error text, helper text, and read-only state.
@State private var messageText = ""
@State private var errorMessage: String? = "Message is too long"
@State private var isReadOnly = false
var body: some View {
BB.TextArea(
text: $messageText,
placeholder: "Enter your message here...",
labelPrimaryText: "Message",
labelSecondaryText: "Optional subtitle",
characterLimit: 500
)
.errorText($errorMessage)
.helperText("Maximum 500 characters allowed")
.readOnly(isReadOnly)
}
States and variants
State priority
The component applies states in the following priority order (highest to lowest):
- Read Only
- Disabled
- Error
- Focused
- Normal
Normal state
The default state when the text area is interactive but not focused.
Visual characteristics:
- Default border color
- Placeholder text visible when empty
- Character count displayed
Focused state
Active when the text area has keyboard focus.
Visual characteristics:
- Brand-colored border
- Cursor visible in the text area
Error state
Displayed when validation fails or an error message is set.
Visual characteristics:
- Danger-colored border
- Error text shown below the text area
Disabled state
Applied when the text area is not interactive.
Visual characteristics:
- Disabled border and text colors
- User interaction blocked
Read-only state
Applied when the text area displays content but does not accept input.
Visual characteristics:
- Content is visible but not editable
Customization
Character limit
Set a custom character limit for the text area.
BB.TextArea(text: $text,
placeholder: "Enter description",
labelPrimaryText: "Description",
characterLimit: 1000)
Helper and error text
Display contextual information or validation errors below the text area.
BB.TextArea(text: $text,
placeholder: "Enter message",
labelPrimaryText: "Message")
.helperText("Keep your message concise")
.errorText($errorMessage)
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.TextArea()
.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 TextArea:
- color/input/default: Default state colors
- color/input/focused: Focused state colors
- color/input/error: Error state colors
- color/input/disabled: Disabled state colors
- color/input/read-only: Read-only state colors
State tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.input.[state].background |
{theme.color.background.default} |
|
Border |
theme.color.input.[state].border |
{theme.color.border.default} |
|
Text |
theme.color.input.[state].value |
{theme.color.foreground.default} |
|
Placeholder |
theme.color.input.[state].placeholder |
{theme.color.foreground.support} |
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Typography (label) |
DesignSystem.shared.fonts.preferredFont(.caption1) |
Typography for label text |
|
Typography (input) |
DesignSystem.shared.fonts.preferredFont(.body) |
Typography for input text |
|
Typography (helper) |
DesignSystem.shared.fonts.preferredFont(.caption1) |
Typography for helper and error text |
|
Spacing |
DesignSystem.shared.spacer |
Spacing between label, input, and helper text |
|
Corner radius |
DesignSystem.shared.cornerRadius |
Corner radius for the text area border |
Localization
The following strings are available for localization:
|
Key |
Default Value |
Description |
|---|---|---|
|
DesignSystem.textArea.characterLimit |
"%1$@/%2$@" |
Character count display format |
|
DesignSystem.textArea.accessibility.characterLimit |
"Character limit is %@, current character count is %@" |
VoiceOver announcement for character count |
To customize these strings, add the keys to your app's Localizable.strings file.
See also
- BB.InputText - For single-line text input
- BB.InputAmount - For currency input