TextArea
TextArea is a themed multi-line text input view using UITextView with title, subtitle, error message, and character counter.
Platform availability: iOS 17.0+
It includes the following features:
- Title and subtitle labels above the text area.
- Error message display with error styling.
- Character counter with configurable limit.
- Fixed height with scrollable content or dynamic height.
- State-based styling (normal, focus, editing, error, disabled).
- Clear button support.
When to use:
- Use TextArea when users need to enter multi-line text, such as descriptions, notes, or comments with character limits.
- Consider using TextInput for single-line text input fields.
Import
import BackbaseDesignSystem
Visual reference
Text area light |
Text area dark |
Text area error |
API reference
TextArea
Properties
|
Property |
Type |
Description |
|---|---|---|
|
borderOptions |
BorderOptions? |
The border color and width |
|
characterLimit |
Int |
The maximum character count. Defaults to 500 |
|
characterLimitLabel |
UILabel |
The character limit label (read-only) |
|
cornerRadius |
CornerRadiusTypes |
The text area's corner radius |
|
disableStyle |
Style<TextArea>? |
The style when disabled |
|
editingStyle |
Style<TextArea>? |
The style when text area is editing |
|
errorLabel |
UILabel |
The error label (read-only) |
|
errorStyle |
Style<TextArea>? |
The style when error message is set |
|
focusStyle |
Style<TextArea>? |
The style when text area is focused |
|
isUserInteractionEnabled |
Bool |
Whether the text area is enabled |
|
normalStyle |
Style<TextArea>? |
The style when not focused, editing, disabled, or in error state |
|
placeholder |
String? |
The placeholder text |
|
placeholderFont |
UIFont? |
The placeholder's font |
|
subviewsVerticalSpacing |
CGFloat |
The vertical spacing between components |
|
subtitleLabel |
UILabel |
The subtitle label (read-only) |
|
text |
String? |
The text displayed in the text area |
|
textContainerInset |
UIEdgeInsets |
The inset of the text container |
|
textView |
UITextView |
The UITextView for entering text (read-only) |
|
textViewContainerPadding |
NSDirectionalEdgeInsets |
The padding for the text view container |
|
textViewContainerView |
UIView |
The container view with border and background (read-only) |
|
textViewHeight |
CGFloat |
The text view's height constraint value |
|
titleHorizontalSpacing |
CGFloat |
The spacing between title and subtitle labels |
|
titleLabel |
UILabel |
The title label (read-only) |
Initializers
- init(style:)
- Initializes a TextArea with the given style.
|
Parameter |
Type |
Description |
|---|---|---|
|
style |
Style<TextArea> |
Style to apply. Defaults to DesignSystem.shared.styles.textArea |
Methods
- enableScrolling()
- Makes the content scrollable with fixed height.
- disableScrolling()
- Disables scrolling and uses dynamic height based on content.
- setError(errorMessage:)
- Sets an error message and applies error styling.
|
Parameter |
Type |
Description |
|---|---|---|
|
errorMessage |
String |
The error message to display |
- clearError()
- Clears the error message and restores normal styling.
- resignFirstResponder()
- Resigns first responder status and hides the clear button.
- Returns: Bool - Whether the operation succeeded
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
characterLimit |
Int |
500 |
|
textViewHeight |
CGFloat |
Component default |
characterLimit
The characterLimit specifies the maximum number of characters the user can enter. The character counter label updates automatically.
let textArea = TextArea()
textArea.characterLimit = 250
textViewHeight
The textViewHeight specifies the height of the text view when scrolling is enabled.
let textArea = TextArea()
textArea.textViewHeight = 150
textArea.enableScrolling()
Usage
Basic usage
Create a text area with default styling:
let textArea = TextArea()
textArea.titleLabel.text = "Description"
textArea.placeholder = "Enter your description here..."
textArea.characterLimit = 500
Setting and clearing errors
let textArea = TextArea()
// Set an error
textArea.setError(errorMessage: "Please enter at least 10 characters")
// Clear the error
textArea.clearError()
Enable/disable scrolling
Control the scrolling behavior:
let textArea = TextArea()
// Set an error
textArea.setError(errorMessage: "Please enter at least 10 characters")
// Clear the error
textArea.clearError()
Custom initialization style
Initialize with a custom style:
let myCustomStyle: Style<TextArea> = { textArea in
textArea.cornerRadius = .fixed(8)
textArea.textView.font = DesignSystem.shared.fonts.preferredFont(.body, .regular)
}
let textArea = TextArea(style: myCustomStyle)
States and variants
Normal state
The default appearance when the text area is not focused and has no errors.
let textArea = TextArea()
Focused state
The appearance when the text area is actively focused for editing. The focusStyle is applied automatically.
Editing state
The appearance while the user is actively typing. The editingStyle is applied automatically.
Error state
The appearance when validation fails or an error message is set.
textArea.setError(errorMessage: "This field is required")
Disabled state
The appearance when the text area is disabled and not interactive.
textArea.isUserInteractionEnabled = false
Customization
Styling
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.textArea |
Default text area style |
State-based styles
Configure styles for different states:
DesignSystem.shared.styles.textArea = DesignSystem.shared.styles.textArea <> { textArea in
let borderSize: CGFloat = 1
let normalStyle: Style<TextArea> = {
let borderOptions = DesignSystem.BorderOptions(color: UIColor.black.cgColor, width: borderSize)
$0.borderOptions = borderOptions
$0.textView.backgroundColor = UIColor.white
$0.textView.textColor = UIColor.black
$0.characterLimitLabel.textColor = UIColor.black
}
textArea.normalStyle = normalStyle
textArea.focusStyle = normalStyle <> {
// Focus state customization
}
textArea.editingStyle = normalStyle <> {
// Editing state customization
}
textArea.errorStyle = normalStyle <> {
// Error state customization
}
textArea.disableStyle = normalStyle <> {
// Disabled state customization
}
}
Updating default style
Extend the default style globally:
DesignSystem.shared.styles.textArea = DesignSystem.shared.styles.textArea <> { textArea in
textArea.cornerRadius = .fixed(12)
textArea.textViewHeight = 150
}
Error handling
Set and clear errors manually:
let textArea = TextArea()
// Show error
textArea.setError(errorMessage: "Please enter at least 10 characters")
// Clear error
textArea.clearError()
Accessibility
The TextArea component 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 |
Description |
Type |
|---|---|---|
|
characterLimitLabel.accessibilityLabel |
The accessible label announcing current and maximum character counts |
String |
|
textView.adjustsFontForContentSizeCategory |
Whether the text view adjusts font size for Dynamic Type |
Bool |
Best practices
- The character limit label has accessibility support with VoiceOver announcing current and maximum character counts.
- Enable adjustsFontForContentSizeCategory on the text view for Dynamic Type support.
- Set descriptive accessibility labels for the text area to clarify its purpose.
Dependencies
- External dependencies: None
- Internal dependencies: None
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
This component uses input tokens from defaultTokens.json. See TextInput for the full list of input-related JSON tokens that also apply to TextArea.
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Colors |
Theme.colors.foreground.default |
Text color |
|
Colors |
Theme.colors.foreground.support |
Placeholder color |
|
Colors |
Theme.colors.foreground.danger |
Error text color |
|
Colors |
Theme.colors.border.default |
Default border color |
|
Colors |
Theme.colors.border.brand |
Focus border color |
|
Colors |
Theme.colors.border.danger |
Error border color |
|
Typography |
DesignSystem.shared.fonts.preferredFont(.body, .regular) |
Text font |
|
Typography |
DesignSystem.shared.fonts.preferredFont(.caption1, .regular) |
Character limit font |
|
Spacing |
DesignSystem.shared.spacer.sm |
Component spacing |
|
Styles |
DesignSystem.shared.styles.textArea |
Default text area style |
Localization
Override the following strings to customize the text:
"DesignSystem.textArea.characterLimit" = "%1$@/%2$@";
"DesignSystem.textArea.accessibility.characterLimit" = "Character limit is %@, current character count is %@";
See also
- TextInput - Single-line text input component