# 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

```kotlin
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.

```kotlin
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.

## Related components

- [Search](https://m3e.ljzapps.app/docs/components/search.md)
- [Menu](https://m3e.ljzapps.app/docs/components/menu.md)
- [Date picker](https://m3e.ljzapps.app/docs/components/date-picker.md)