Overview
InputText is a Jetpack Compose single-line text input field with comprehensive styling and state management for form inputs.
It includes the following features:
- Single-line text input with configurable keyboard options
- Optional leading icon support
- Clear button when focused with content
- Primary and secondary label support
- Helper text and error state visualization
- Read-only and disabled states
- Consistent styling via theme composition locals
Visual reference
API reference
InputText
A composable function that displays a single-line text input field.
@Composable
fun InputText(
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,
leadingIcon: Painter? = null,
leadingIconContentDescription: String? = null,
keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
keyboardActions: KeyboardActions = KeyboardActions(),
)
Properties
|
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 |
|
leadingIcon |
Painter? |
Optional icon displayed at the start of the field |
|
leadingIconContentDescription |
String? |
Accessibility description for the leading icon |
|
keyboardOptions |
KeyboardOptions |
Configuration for the software keyboard |
|
keyboardActions |
KeyboardActions |
Actions triggered by IME keyboard |
Usage
Basic usage
Create a basic text input with state management.
import com.backbase.android.design.component.InputText
import androidx.compose.ui.text.input.TextFieldValue
@Composable
fun TextInputExample() {
var text by remember { mutableStateOf(TextFieldValue()) }
InputText(
value = text,
onValueChange = { text = it },
primaryLabelText = "Full Name",
placeholderText = "Enter your name",
)
}
Common use cases
With leading icon
Add a leading icon to provide visual context.
InputText(
value = text,
onValueChange = { text = it },
primaryLabelText = "Search",
placeholderText = "Search...",
leadingIcon = Icons.Painter.iconSearch,
leadingIconContentDescription = "Search",
)
With labels and helper text
InputText(
value = text,
onValueChange = { text = it },
primaryLabelText = "Email Address",
secondaryLabelText = "(required)",
helperText = "We'll never share your email",
placeholderText = "email@example.com",
)
Error state
Display validation errors.
InputText(
value = text,
onValueChange = { text = it },
isError = true,
helperText = "Please enter a valid email address",
leadingIcon = Icons.Painter.iconEmail,
)
With keyboard options
Configure keyboard behavior for specific input types.
InputText(
value = text,
onValueChange = { text = it },
primaryLabelText = "Phone Number",
keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Phone),
)
Email input
InputText(
value = text,
onValueChange = { text = it },
primaryLabelText = "Email",
keyboardOptions = KeyboardOptions(
keyboardType = KeyboardType.Email,
imeAction = ImeAction.Next
),
)
Disabled state
Disable user interaction.
InputText(
value = text,
onValueChange = { },
enabled = false,
primaryLabelText = "Locked Field",
)
Read-only state
Display text without allowing edits.
InputText(
value = text,
onValueChange = { },
readOnly = true,
primaryLabelText = "Account Number",
)
States and variants
Empty state
No text entered.
Visual characteristics:
- Placeholder text displayed
- Leading icon visible if provided
- No trailing clear button
Filled state
Text has been entered.
Visual characteristics:
- User text displayed
- Leading icon visible if provided
- Clear button appears when focused
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.
Visual characteristics:
- Error border color
- Error icon displayed instead of clear button
- Helper text in error color
Disabled state
Non-interactive state.
Visual characteristics:
- Grayed out appearance
- Leading icon dimmed
- Field not editable
Read-only state
Displays value without allowing edits.
Visual characteristics:
- Standard text appearance
- No editing capability
- No clear button
Customization
Styling
The component uses InputTextColorScheme for colors and InputTextLayout for layout properties.
Design tokens
The InputText 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, and helper text
- Leading icon colors for each state
- Trailing icon colors for clear and error icons
- Typography styles for text, labels, and helper text
- Cursor color
- Minimum field size dimensions
Accessibility
- Leading icon can have content description
- Clear button accessible when focused with content
- Error states announced via accessibility semantics
- Labels provide context for screen readers
- Keyboard navigation supported
Dependencies
- External dependencies: None
- Internal dependencies:
- LocalInputTextColorScheme: Color scheme composition local
- LocalInputTextLayout: Layout composition local
- Icons.Painter.iconError: Error icon