SecureTextField

Composable Component

Text fields allow users to enter text into a UI. SecureTextField is specifically designed for password entry fields. It only supports a single line of content and comes with default settings that are appropriate for entering secure content. Additionally, some context menu actions like cut, copy, and drag are disabled for added security.

Common
@Composable
fun SecureTextField(
    state: TextFieldState,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    textStyle: TextStyle = LocalTextStyle.current,
    labelPosition: TextFieldLabelPosition = TextFieldLabelPosition.Attached(),
    label: @Composable (TextFieldLabelScope.() -> Unit)? = null,
    placeholder: @Composable (() -> Unit)? = null,
    leadingIcon: @Composable (() -> Unit)? = null,
    trailingIcon: @Composable (() -> Unit)? = null,
    prefix: @Composable (() -> Unit)? = null,
    suffix: @Composable (() -> Unit)? = null,
    supportingText: @Composable (() -> Unit)? = null,
    isError: Boolean = false,
    inputTransformation: InputTransformation? = null,
    textObfuscationMode: TextObfuscationMode = TextObfuscationMode.RevealLastTyped,
    textObfuscationCharacter: Char = DefaultObfuscationCharacter,
    keyboardOptions: KeyboardOptions = SecureTextFieldKeyboardOptions,
    onKeyboardAction: KeyboardActionHandler? = null,
    onTextLayout: (Density.(getResult: () -> TextLayoutResult?) -> Unit)? = null,
    shape: Shape = TextFieldDefaults.shape,
    colors: TextFieldColors = TextFieldDefaults.colors(),
    contentPadding: PaddingValues =
        if (label == null || labelPosition is TextFieldLabelPosition.Above) {
            TextFieldDefaults.contentPaddingWithoutLabel()
        } else {
            TextFieldDefaults.contentPaddingWithLabel()
        },
    interactionSource: MutableInteractionSource? = null,
)

Parameters
state TextFieldState object that holds the internal editing state of the text field.
modifier the Modifier to be applied to this text field.
enabled controls the enabled state of this text field. When false, this component will not respond to user input, and it will appear visually disabled and disabled to accessibility services.
textStyle the style to be applied to the input text. Defaults to LocalTextStyle.
labelPosition the position of the label. See TextFieldLabelPosition.
label the optional label to be displayed with this text field. The default text style uses Typography.bodySmall when minimized and Typography.bodyLarge when expanded.
placeholder the optional placeholder to be displayed when the input text is empty. The default text style uses Typography.bodyLarge.
leadingIcon the optional leading icon to be displayed at the beginning of the text field container.
trailingIcon the optional trailing icon to be displayed at the end of the text field container.
prefix the optional prefix to be displayed before the input text in the text field.
suffix the optional suffix to be displayed after the input text in the text field.
supportingText the optional supporting text to be displayed below the text field.
isError indicates if the text field's current value is in error. When true, the components of the text field will be displayed in an error color, and an error will be announced to accessibility services.
inputTransformation optional InputTransformation that will be used to transform changes to the TextFieldState made by the user. The transformation will be applied to changes made by hardware and software keyboard events, pasting or dropping text, accessibility services, and tests. The transformation will not be applied when changing the state programmatically, or when the transformation is changed. If the transformation is changed on an existing text field, it will be applied to the next user edit. The transformation will not immediately affect the current state.
textObfuscationMode the method used to obscure the input text.
textObfuscationCharacter the character to use while obfuscating the text. It doesn't have an effect when textObfuscationMode is set to TextObfuscationMode.Visible.
keyboardOptions software keyboard options that contains configuration such as KeyboardType and ImeAction. This component by default configures KeyboardOptions for a secure text field by disabling auto correct and setting KeyboardType to KeyboardType.Password.
onKeyboardAction called when the user presses the action button in the input method editor (IME), or by pressing the enter key on a hardware keyboard. By default this parameter is null, and would execute the default behavior for a received IME Action e.g., ImeAction.Done would close the keyboard, ImeAction.Next would switch the focus to the next focusable item on the screen.
onTextLayout Callback that is executed when the text layout becomes queryable. The callback receives a function that returns a TextLayoutResult if the layout can be calculated, or null if it cannot. The function reads the layout result from a snapshot state object, and will invalidate its caller when the layout result changes. A TextLayoutResult object contains paragraph information, size of the text, baselines and other details. Density scope is the one that was used while creating the given text layout.
shape defines the shape of this text field's container.
colors TextFieldColors that will be used to resolve the colors used for this text field in different states. See TextFieldDefaults.colors.
contentPadding the padding applied to the inner text field that separates it from the surrounding elements of the text field. Note that the padding values may not be respected if they are incompatible with the text field's size constraints or layout. See TextFieldDefaults.contentPaddingWithLabel and TextFieldDefaults.contentPaddingWithoutLabel.
interactionSource an optional hoisted MutableInteractionSource for observing and emitting Interactions for this text field. You can use this to change the text field's appearance or preview the text field in different states. Note that if null is provided, interactions will still happen internally.

Code Examples

PasswordTextField

@Preview
@Composable
fun PasswordTextField() {
    var passwordHidden by rememberSaveable { mutableStateOf(true) }
    SecureTextField(
        state = rememberTextFieldState(),
        label = { Text("Enter password") },
        textObfuscationMode =
            if (passwordHidden) TextObfuscationMode.RevealLastTyped
            else TextObfuscationMode.Visible,
        trailingIcon = {
            // Provide localized description for accessibility services
            val description = if (passwordHidden) "Show password" else "Hide password"
            TooltipBox(
                positionProvider =
                    TooltipDefaults.rememberTooltipPositionProvider(TooltipAnchorPosition.Above),
                tooltip = { PlainTooltip { Text(description) } },
                state = rememberTooltipState(),
            ) {
                IconButton(onClick = { passwordHidden = !passwordHidden }) {
                    val visibilityIcon =
                        if (passwordHidden) Icons.Filled.Visibility else Icons.Filled.VisibilityOff
                    Icon(imageVector = visibilityIcon, contentDescription = description)
                }
            }
        },
    )
}