# Password field

> A text field that hides what is typed and can reveal it on request.

- Category: Selection and input
- API status: Stable
- Compose APIs: `SecureTextField`, `OutlinedSecureTextField`, `TextObfuscationMode`
- Interactive page: https://m3e.ljzapps.app/#components/secure-text-field

## When to use

SecureTextField masks the input and blocks copy and cut, which is what a password field needs. By default it briefly reveals the last typed character, which helps on touch keyboards.

Offer a visibility toggle so people can check what they typed. Describe the toggle state in its content description.

## Playground

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

## Examples

### With visibility toggle

```kotlin
val password = rememberTextFieldState()
var visible by remember { mutableStateOf(false) }

OutlinedSecureTextField(
    state = password,
    label = { Text("Password") },
    textObfuscationMode = if (visible) TextObfuscationMode.Visible else TextObfuscationMode.RevealLastTyped,
    trailingIcon = {
        IconButton(onClick = { visible = !visible }) {
            Icon(
                imageVector = if (visible) Icons.Rounded.VisibilityOff else Icons.Rounded.Visibility,
                contentDescription = if (visible) "Hide password" else "Show password",
            )
        }
    },
    modifier = Modifier.widthIn(max = 360.dp).fillMaxWidth(),
)
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `state` | `TextFieldState` |  | Holds the secret text. |
| `textObfuscationMode` | `TextObfuscationMode` | `RevealLastTyped` | Hidden, RevealLastTyped or Visible. |
| `trailingIcon` | `@Composable (() -> Unit)?` | `null` | Place the visibility toggle here. |

## Guidelines

Do:
- Allow paste so password managers work.
- Explain the rules before the user types.

Don't:
- Do not clear the field on a failed attempt.
- Do not use it for non secret input.

## Accessibility

- Mark the field with the right autofill hint so password managers can fill it.
- Do not announce the typed characters when the field is hidden.

## Related components

- [Text field](https://m3e.ljzapps.app/docs/components/text-field.md)
- [Icon button](https://m3e.ljzapps.app/docs/components/icon-button.md)