# SecureTextField

Common/AllAndroid/JVM

## Functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/material3/SecureTextField.composable#SecureTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.material3.TextFieldLabelPosition,kotlin.Function1,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.foundation.text.input.TextObfuscationMode,kotlin.Char,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,kotlin.Function2,androidx.compose.ui.graphics.Shape,androidx.compose.material3.TextFieldColors,androidx.compose.foundation.layout.PaddingValues,androidx.compose.foundation.interaction.MutableInteractionSource)( state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextFieldState, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, textStyle: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextStyle, labelPosition: https://developer.android.com/reference/kotlin/androidx/compose/material3/TextFieldLabelPosition, label: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/material3/TextFieldLabelScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, placeholder: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, leadingIcon: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, trailingIcon: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, prefix: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, suffix: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, supportingText: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, isError: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, inputTransformation: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/InputTransformation?, textObfuscationMode: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextObfuscationMode, textObfuscationCharacter: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-char/index.html, keyboardOptions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions, onKeyboardAction: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/KeyboardActionHandler?, onTextLayout: (https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Density.(getResult: () -> https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextLayoutResult?) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, shape: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape, colors: https://developer.android.com/reference/kotlin/androidx/compose/material3/TextFieldColors, contentPadding: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/PaddingValues, interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource? )` [Material Design filled text field for secure content](https://m3.material.io/components/text-fields/overview) | Cmn |

## Functions

### SecureTextField

Cmn Artifact: [androidx.compose.material3:material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) [View Source](https://cs.android.com/search?q=file:androidx/compose/material3/SecureTextField.kt+function:SecureTextField)

```
@Composable
fun SecureTextField(
    state: TextFieldState,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    textStyle: TextStyle = LocalTextStyle.current,
    labelPosition: TextFieldLabelPosition = TextFieldLabelPosition.Inside(),
    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.System,
    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
): Unit
```

[Material Design filled text field for secure content](https://m3.material.io/components/text-fields/overview)

Text fields allow users to enter text into a UI. `https://developer.android.com/reference/kotlin/androidx/compose/material3/SecureTextField.composable#SecureTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.material3.TextFieldLabelPosition,kotlin.Function1,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.foundation.text.input.TextObfuscationMode,kotlin.Char,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,kotlin.Function2,androidx.compose.ui.graphics.Shape,androidx.compose.material3.TextFieldColors,androidx.compose.foundation.layout.PaddingValues,androidx.compose.foundation.interaction.MutableInteractionSource)` 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.

Filled text fields have more visual emphasis than outlined text fields, making them stand out when surrounded by other content and components. For an outlined version, see `https://developer.android.com/reference/kotlin/androidx/compose/material3/OutlinedSecureTextField.composable#OutlinedSecureTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.material3.TextFieldLabelPosition,kotlin.Function1,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.foundation.text.input.TextObfuscationMode,kotlin.Char,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,kotlin.Function2,androidx.compose.ui.graphics.Shape,androidx.compose.material3.TextFieldColors,androidx.compose.foundation.layout.PaddingValues,androidx.compose.foundation.interaction.MutableInteractionSource)`.

Example of a password text field:

```kotlin
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.foundation.text.input.TextObfuscationMode
import androidx.compose.foundation.text.input.rememberTextFieldState
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Visibility
import androidx.compose.material.icons.filled.VisibilityOff
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.PlainTooltip
import androidx.compose.material3.SecureTextField
import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.material3.TooltipAnchorPosition
import androidx.compose.material3.TooltipBox
import androidx.compose.material3.TooltipDefaults
import androidx.compose.material3.rememberTooltipState
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.Modifier
import androidx.compose.ui.semantics.LiveRegionMode
import androidx.compose.ui.semantics.liveRegion
import androidx.compose.ui.semantics.paneTitle
import androidx.compose.ui.semantics.semantics
import androidx.compose.ui.text.input.KeyboardType

var passwordHidden by rememberSaveable { mutableStateOf(true) }
SecureTextField(
    state = rememberTextFieldState(),
    label = { Text("Enter password") },
    keyboardOptions =
        KeyboardOptions(
            autoCorrectEnabled = false,
            keyboardType =
                if (passwordHidden) KeyboardType.Password else KeyboardType.PasswordVisible,
        ),
    textObfuscationMode =
        if (passwordHidden) TextObfuscationMode.System 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(
                    modifier =
                        Modifier.semantics {
                            // TODO(b/496338253): Remove this modifier once bug where tooltip
                            //  text is not announced by a11y screen readers is resolved.
                            liveRegion = LiveRegionMode.Assertive
                            paneTitle = description
                        }
                ) {
                    Text(description)
                }
            },
            state = rememberTooltipState(),
        ) {
            IconButton(onClick = { passwordHidden = !passwordHidden }) {
                val visibilityIcon =
                    if (passwordHidden) Icons.Filled.Visibility else Icons.Filled.VisibilityOff
                Icon(imageVector = visibilityIcon, contentDescription = description)
            }
        }
    },
)
```

| Parameters |
|---|---|
| `state: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextFieldState` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextFieldState` object that holds the internal editing state of the text field. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | the `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` to be applied to this text field. |
| `enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | 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: https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextStyle = LocalTextStyle.current` | the style to be applied to the input text. Defaults to `https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#LocalTextStyle()`. |
| `labelPosition: https://developer.android.com/reference/kotlin/androidx/compose/material3/TextFieldLabelPosition = TextFieldLabelPosition.Inside()` | the position of the label. See `https://developer.android.com/reference/kotlin/androidx/compose/material3/TextFieldLabelPosition`. |
| `label: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/material3/TextFieldLabelScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | the optional label to be displayed with this text field. The default text style uses `https://developer.android.com/reference/kotlin/androidx/compose/material3/Typography#bodySmall()` when minimized and `https://developer.android.com/reference/kotlin/androidx/compose/material3/Typography#bodyLarge()` when expanded. |
| `placeholder: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | the optional placeholder to be displayed when the input text is empty. The default text style uses `https://developer.android.com/reference/kotlin/androidx/compose/material3/Typography#bodyLarge()`. |
| `leadingIcon: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | the optional leading icon to be displayed at the beginning of the text field container. |
| `trailingIcon: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | the optional trailing icon to be displayed at the end of the text field container. |
| `prefix: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | the optional prefix to be displayed before the input text in the text field. |
| `suffix: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | the optional suffix to be displayed after the input text in the text field. |
| `supportingText: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | the optional supporting text to be displayed below the text field. |
| `isError: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | 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: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/InputTransformation? = null` | optional `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/InputTransformation` that will be used to transform changes to the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/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 `https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#SecureTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.material3.TextFieldLabelPosition,kotlin.Function1,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.foundation.text.input.TextObfuscationMode,kotlin.Char,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,kotlin.Function2,androidx.compose.ui.graphics.Shape,androidx.compose.material3.TextFieldColors,androidx.compose.foundation.layout.PaddingValues,androidx.compose.foundation.interaction.MutableInteractionSource)` 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 `https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#SecureTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.material3.TextFieldLabelPosition,kotlin.Function1,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.foundation.text.input.TextObfuscationMode,kotlin.Char,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,kotlin.Function2,androidx.compose.ui.graphics.Shape,androidx.compose.material3.TextFieldColors,androidx.compose.foundation.layout.PaddingValues,androidx.compose.foundation.interaction.MutableInteractionSource)`. |
| `textObfuscationMode: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextObfuscationMode = TextObfuscationMode.System` | the method used to obscure the input text. |
| `textObfuscationCharacter: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-char/index.html = DefaultObfuscationCharacter` | the character to use while obfuscating the text. It doesn't have an effect when `https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#SecureTextField(androidx.compose.foundation.text.input.TextFieldState,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.text.TextStyle,androidx.compose.material3.TextFieldLabelPosition,kotlin.Function1,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.foundation.text.input.InputTransformation,androidx.compose.foundation.text.input.TextObfuscationMode,kotlin.Char,androidx.compose.foundation.text.KeyboardOptions,androidx.compose.foundation.text.input.KeyboardActionHandler,kotlin.Function2,androidx.compose.ui.graphics.Shape,androidx.compose.material3.TextFieldColors,androidx.compose.foundation.layout.PaddingValues,androidx.compose.foundation.interaction.MutableInteractionSource)` is set to `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextObfuscationMode#Visible()`. |
| `keyboardOptions: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions = SecureTextFieldKeyboardOptions` | software keyboard options that contains configuration such as `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/KeyboardType` and `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/ImeAction`. This component by default configures `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/KeyboardOptions` for a secure text field by disabling auto correct and setting `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/KeyboardType` to `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/KeyboardType#Password()`. If using `https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/TextObfuscationMode#Visible()`, consider passing `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/KeyboardType#PasswordVisible()` instead to indicate to the IME that the input is visible. |
| `onKeyboardAction: https://developer.android.com/reference/kotlin/androidx/compose/foundation/text/input/KeyboardActionHandler? = null` | 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., `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/ImeAction#Done()` would close the keyboard, `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/input/ImeAction#Next()` would switch the focus to the next focusable item on the screen. |
| `onTextLayout: (https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Density.(getResult: () -> https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextLayoutResult?) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | Callback that is executed when the text layout becomes queryable. The callback receives a function that returns a `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/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 `https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextLayoutResult` object contains paragraph information, size of the text, baselines and other details. `https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Density` scope is the one that was used while creating the given text layout. |
| `shape: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape = TextFieldDefaults.shape` | defines the shape of this text field's container. |
| `colors: https://developer.android.com/reference/kotlin/androidx/compose/material3/TextFieldColors = TextFieldDefaults.colors()` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/TextFieldColors` that will be used to resolve the colors used for this text field in different states. See `https://developer.android.com/reference/kotlin/androidx/compose/material3/TextFieldDefaults#colors()`. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/PaddingValues = if (label == null || labelPosition is TextFieldLabelPosition.Above) { TextFieldDefaults.contentPaddingWithoutLabel() } else { TextFieldDefaults.contentPaddingWithLabel() }` | 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 `https://developer.android.com/reference/kotlin/androidx/compose/material3/TextFieldDefaults#contentPaddingWithLabel(androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp)` and `https://developer.android.com/reference/kotlin/androidx/compose/material3/TextFieldDefaults#contentPaddingWithoutLabel(androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp)`. |
| `interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource? = null` | an optional hoisted `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/MutableInteractionSource` for observing and emitting `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/Interaction`s 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. |