Overview
TextArea is a Jetpack Compose multi-line text input field with character limit tracking and comprehensive state management. It includes the following features:
- Multi-line text input with minimum 3 lines displayed
- Character counter with configurable limit
- Visual warning when character limit is reached
- Clear button when focused with content
- Primary and secondary label support
- Helper text and error state visualization
- Read-only and disabled states
Visual reference
API reference
TextArea
A composable function that displays a multi-line text input field with character counting.
@Composable
fun TextArea(
value: TextFieldValue,
onValueChange: (text: TextFieldValue) -> Unit,
modifier: Modifier = Modifier,
enabled: Boolean = true,
isError: Boolean = false,
readOnly: Boolean = false,
primaryLabelText: String? = null,
secondaryLabelText: String? = null,
placeholderText: String? = null,
helperText: String? = null,
characterLimiter: Int = 500,
keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
keyboardActions: KeyboardActions = KeyboardActions(),
)
Parameters
|
Property |
Type |
Description |
|---|---|---|
|
value |
TextFieldValue |
Current text field value |
|
onValueChange |
(TextFieldValue) -> Unit |
Callback invoked with updated value |
|
modifier |
Modifier |
Modifier for styling or layout |
|
enabled |
Boolean |
Whether input is editable. Defaults to true |
|
isError |
Boolean |
Whether to show error state visuals. Defaults to false |
|
readOnly |
Boolean |
Disables editing but retains visual style. Defaults to false |
|
primaryLabelText |
String? |
Main label above the field |
|
secondaryLabelText |
String? |
Optional secondary label |
|
placeholderText |
String? |
Text shown when field is empty |
|
helperText |
String? |
Supporting or error text below the field |
|
characterLimiter |
Int |
Maximum number of characters allowed. Defaults to 500 |
|
keyboardOptions |
KeyboardOptions |
Configuration for the software keyboard |
|
keyboardActions |
KeyboardActions |
Actions triggered by IME keyboard |
Usage
Basic usage
Create a basic text area with state management.
import com.backbase.android.design.component.TextArea
import androidx.compose.ui.text.input.TextFieldValue
@Composable
fun TextAreaExample() {
var text by remember { mutableStateOf(TextFieldValue()) }
TextArea(
value = text,
onValueChange = { text = it },
primaryLabelText = "Description",
placeholderText = "Enter a description...",
)
}
Common use cases
With character limit
Customize the character limit.
TextArea(
value = text,
onValueChange = { text = it },
primaryLabelText = "Bio",
placeholderText = "Tell us about yourself",
characterLimiter = 200 // Displays: 0/200 counter
)
With labels and helper text
TextArea(
value = text,
onValueChange = { text = it },
primaryLabelText = "Comments",
secondaryLabelText = "(optional)",
helperText = "Share any additional details",
placeholderText = "Enter your comments...",
)
Error state
Display validation errors.
TextArea(
value = text,
onValueChange = { text = it },
isError = true,
helperText = "This field is required",
)
With keyboard options
Configure keyboard behavior.
TextArea(
value = text,
onValueChange = { text = it },
primaryLabelText = "Message",
keyboardOptions = KeyboardOptions(
capitalization = KeyboardCapitalization.Sentences,
imeAction = ImeAction.Done
),
)
Disabled state
Disable user interaction.
TextArea(
value = text,
onValueChange = { },
enabled = false,
primaryLabelText = "Locked Notes",
)
Read-only state
Display text without allowing edits.
TextArea(
value = text,
onValueChange = { },
readOnly = true,
primaryLabelText = "Terms and Conditions",
)
States and variants
Empty state
No text entered.
Visual characteristics:
- Placeholder text displayed
- Character counter shows "0/[limit]"
- Minimum 3 lines height
Filled state
Text has been entered.
Visual characteristics:
- User text displayed
- Character counter updates: "[count]/[limit]"
- Clear button appears when focused
Character limit reached state
Text length equals or exceeds the character limit.
Visual characteristics:
- Border color changes to error color
- Counter text changes to error color
- Visual warning that limit is reached
Focused state
Field has input focus.
Visual characteristics:
- Highlighted border color
- Cursor visible
- Clear button visible if field has content
Error state
Displays when validation fails or character limit reached.
Visual characteristics:
- Error border color
- Error icon displayed instead of clear button
- Helper text in error color
- Counter in error color if limit reached
Disabled state
Non-interactive state.
Visual characteristics:
- Grayed out appearance
- Field not editable
- Counter visible but dimmed
Read-only state
Displays value without allowing edits.
Visual characteristics:
- Standard text appearance
- No editing capability
- No clear button
- Counter still visible
Customization
Styling
The component uses TextAreaColorScheme for colors and TextAreaLayout for layout properties.
Design tokens
The TextArea component uses the following design tokens:
- Border colors for each state: enabled, focused, error, disabled, read-only
- Background colors for each state
- Text colors for input value, labels, placeholders, helper text, and counter
- Trailing icon colors for clear and error icons
- Typography styles for text, labels, helper text, and counter
- Cursor color
- Minimum field size dimensions
Accessibility
- Multi-line input announced by screen readers
- Character counter announced for accessibility
- Clear button accessible when focused with content
- Error states announced via accessibility semantics
- Labels provide context for screen readers
Dependencies
- External dependencies: None
- Internal dependencies:
- LocalTextAreaColorScheme: Color scheme composition local
- LocalTextAreaLayout: Layout composition local
- Icons.Painter.iconError: Error icon