Text field

Lets people enter and edit text. Filled or outlined, with labels, icons and helper text.

Category: Selection and input
API status: Stable
Compose APIs: TextField, OutlinedTextField, SecureTextField, TextFieldState
Interactive page: https://m3e.ljzapps.app/#components/text-field

When to use

Use filled text fields for the highest emphasis and outlined ones in dense forms. Always provide a label that stays visible, and use supporting text to explain format or errors.

TextFieldState based overloads keep the text in a state holder instead of a String, which suits input transformations and secure fields.

Playground

The interactive page has a playground with live property controls for this component and generated code.

Examples

Filled and outlined

var text by rememberSaveable { mutableStateOf("") }

Column(Modifier.widthIn(max = 360.dp).fillMaxWidth(), verticalArrangement = Arrangement.spacedBy(16.dp)) {
    TextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Filled") },
        modifier = Modifier.fillMaxWidth(),
    )
    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Outlined") },
        modifier = Modifier.fillMaxWidth(),
    )
}

Secure

Hides the input and offers a reveal toggle through the trailing icon.

val password = rememberTextFieldState()

SecureTextField(
    state = password,
    label = { Text("Password") },
    modifier = Modifier.widthIn(max = 360.dp).fillMaxWidth(),
)

Parameters

Name	Type	Default	Description
`value / state`	`String \| TextFieldState`		The text, as a value or a state holder.
`label`	`@Composable (() -> Unit)?`	`null`	Floats above the text when focused or filled.
`supportingText`	`@Composable (() -> Unit)?`	`null`	Helper or error message below the field.
`isError`	`Boolean`	`false`	Switches to error colors.
`leadingIcon / trailingIcon`	`@Composable (() -> Unit)?`	`null`	Icons inside the field.
`keyboardOptions`	`KeyboardOptions`	`Default`	Keyboard type and IME action.

Guidelines

Do:

Show validation after the user leaves the field.
Keep labels short.

Don't:

Do not use placeholder text as the label.
Do not clear the field on error.

Accessibility

The label is the accessible name. Do not use only a placeholder.
Link errors to the field with supporting text, and do not signal errors by color alone.
Autofill hints help users complete forms faster.