Filled Secure Text Field

A secure text field whose label is inside its box: a password, a PIN or a card's security code in the filled box of PantrixFilledTextField.

import com.pantrixui.components.inputs.filledsecuretextfield.PantrixFilledSecureTextField

• The label inside the box. label rests in the text's place while the field is empty and without the focus; with the focus, or while the field holds a text, it moves up to its own line above the text. placeholder shows while the label is out of its place: while the field is empty and has the focus.
• Fill and outline. At rest the box is filled and has no outline; it is outlined with the focus and in error. A disabled field has no fill.
• Hidden text. The platform is told that the field holds a password, and while the text is hidden it is given dots in place of the text: a screen reader does not read the password out, while a password manager still fills the field and saves it.
• The reveal button. A press on the eye button with a mouse leaves the caret where it is. With a keyboard it is a Tab stop of its own, after the field; the keyboard's "Next" key goes past it. That the text was shown is not saved. showRevealButton = false takes the button away.
• Obfuscation mode. textObfuscationMode says how the hidden text is drawn, and textObfuscationCharacter which character is drawn in place of the dot.
• Reading the text. The text is read from the state: state.text when it is used, snapshotFlow to follow it as it is typed. There is no overload that takes a value and an onValueChange.
• Form. The overload that takes a field gets its value, its error and its name from its field in the form; given form, the keyboard's action key submits the form.
• What comes from the filled field. supportingText, error, leadingIcon, showClearButton and maxLength are as they are in the filled text field. trailingIcon stands after the clear button and the reveal button.
• Automation. With tagKey the field is named FilledSecureTextField_<tagKey>, the clear button FilledSecureTextFieldClear_<tagKey> and the reveal button FilledSecureTextFieldReveal_<tagKey>. The field never reports its text.

Examples

At its plainest

The least there is to write: a TextFieldState and a label. The label is inside the box: it rests in the text's place while the field is empty, and moves up to its own line above the text when the field is pressed. What is typed is drawn as dots, and cannot be cut or copied.

Type something and press the eye button at the end of the box: the text shows, and another press hides it again. A press with a mouse does not take the caret out of the field; with a keyboard, Tab stops at the button after the field. That the text was shown is not saved.

PantrixFilledSecureTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Vault password",
    tagKey = "safe_password"
)

Supporting text and error

supportingText stands under the box. error = true outlines the box in the danger colour; the supporting text and the caret turn to that colour too, and a screen reader announces the message as the error. The label keeps its own colour.

The field starts in error: there is a space in its text. Press the eye button to see the text, and delete the space: the error goes. It is the caller, not the field, that works out the error; here by reading password.text.

val password = rememberTextFieldState("secret password")
val hasSpace = password.text.contains(' ')
PantrixFilledSecureTextField(
    state = password,
    modifier = Modifier.fillMaxWidth(),
    label = "App lock",
    supportingText = if (hasSpace) "A password cannot contain a space" else "A password without spaces",
    error = hasSpace,
    showClearButton = true,
    tagKey = "app_lock"
)

Icon, clear button and count

leadingIcon stands before the label and the text. A slot does not size what is put in it: the example itself gives this icon the size in the filled field's style, PantrixTheme.style(FilledTextFieldStyle).iconSize. What is at the box's end is always in the same order: first the clear button, then the button that shows the text, and last trailingIcon, where one is given.

The clear button shows while the field is not empty, leaves the caret in the field and is no stop for Tab; the eye button is a Tab stop. maxLength = 16 turns down a longer password, and writes the count under the box.

PantrixFilledSecureTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Admin password",
    leadingIcon = {
        PantrixIcon(
            imageVector = PantrixIcons.Person,
            contentDescription = null,
            size = PantrixTheme.style(FilledTextFieldStyle).iconSize
        )
    },
    showClearButton = true,
    maxLength = 16,
    tagKey = "admin_password"
)

A password change bound to a form

Both fields get their value, their error and their name from their field in the form. In the current password the keyboard's "Next" key moves the focus to the new password; in the new password the action key submits the form through the "Change password" button. Leave both fields empty and press the button: the form is not submitted, and the first field in error takes the focus.

The platform is told that the new password is one that is being chosen (ContentType.NewPassword): a password manager offers to suggest a new one here, not to fill in the saved one. The current password was given no contentType: the field holds ContentType.Password.

val snackbars = LocalPantrixSnackbars.current
val scope = rememberCoroutineScope()
val form = rememberFormState()
PantrixFilledSecureTextField(
    field = form.field("current_password", initial = "", Rules.notBlank("Enter your current password")),
    modifier = Modifier.fillMaxWidth(),
    form = form,
    label = "Current password",
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next)
)
PantrixFilledSecureTextField(
    field = form.field("new_password", initial = "", Rules.minLength(8, "The new password must be at least 8 characters")),
    modifier = Modifier.fillMaxWidth(),
    form = form,
    label = "New password",
    supportingText = "At least 8 characters",
    showClearButton = true,
    contentType = ContentType.NewPassword
)
PantrixButton(
    text = "Change password",
    onClick = {
        scope.launch {
            form.submit { snackbars?.show(message = "Password changed", tagKey = "password_changed") }
        }
    },
    form = form,
    tagKey = "change_password"
)

A security code read when it is used

The three-digit security code on the back of a card: its keyboard is the number keyboard, an input transformation turns down what is not a digit, and its count is not shown. The eye button stays, so that the user can compare the code they typed with the one on the card.

The text is read from the state when it is used: code.text, when the button is pressed. It is carried nowhere in between; the field's state is its only source. The notification says how many digits were received, not the code itself.

val snackbars = LocalPantrixSnackbars.current
val scope = rememberCoroutineScope()
val code = rememberTextFieldState()
PantrixFilledSecureTextField(
    state = code,
    modifier = Modifier.fillMaxWidth(),
    label = "Security code",
    placeholder = "000",
    supportingText = "The three digits on the back of the card",
    maxLength = 3,
    showCharacterCount = false,
    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.NumberPassword),
    inputTransformation = DigitsOnly,
    contentType = ContentType.CreditCardSecurityCode,
    tagKey = "card_code"
)
PantrixButton(
    text = "Verify card",
    onClick = {
        val entered = code.text.toString()
        val message = when (entered.length) {
            3 -> "Code received: ${entered.length} digits"
            else -> "The code must be 3 digits, you entered ${entered.length}"
        }
        scope.launch { snackbars?.show(message = message, tagKey = "card_code_read") }
    },
    tagKey = "verify_card"
)

private val DigitsOnly = InputTransformation {
    if (!asCharSequence().all(Char::isDigit)) revertAllChanges()
}

A text followed as it is typed

A caller that wants the text as it is typed follows it from the state: snapshotFlow { state.text.toString() } gives every change, here to a String the caller holds. The supporting text is made from that String, and says what the password still lacks.

The flow goes one way: the text flows from the field to the caller. Carrying it to a ViewModel is written the same way: each change is reported to the ViewModel inside collect.

var password by remember { mutableStateOf("") }
val state = rememberTextFieldState(password)
LaunchedEffect(state) {
    snapshotFlow { state.text.toString() }.collect { password = it }
}
PantrixFilledSecureTextField(
    state = state,
    modifier = Modifier.fillMaxWidth(),
    label = "New account password",
    supportingText = when {
        password.isEmpty() -> "At least 10 characters, including a digit"
        password.length < 10 -> "Characters to go: ${10 - password.length}"
        password.none(Char::isDigit) -> "Add a digit"
        else -> "The password is good enough"
    },
    contentType = ContentType.NewPassword,
    tagKey = "followed_password"
)

A PIN that is never shown

showRevealButton = false takes away the eye button: the text stays as textObfuscationMode draws it. With TextObfuscationMode.Hidden the last digit typed shows on no platform; the default, System, would show the last character typed for a moment on Android, where the system's own setting says so. textObfuscationCharacter draws an asterisk in place of the dot.

Its keyboard is a PIN's: KeyboardType.NumberPassword. maxLength = 4 takes no fifth digit, and writes the count under the box.

PantrixFilledSecureTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Card PIN",
    supportingText = "Four digits",
    showRevealButton = false,
    maxLength = 4,
    textObfuscationMode = TextObfuscationMode.Hidden,
    textObfuscationCharacter = '*',
    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.NumberPassword),
    inputTransformation = DigitsOnly,
    tagKey = "card_pin"
)

private val DigitsOnly = InputTransformation {
    if (!asCharSequence().all(Char::isDigit)) revertAllChanges()
}

Disabled and read-only

enabled = false takes the field's fill away: the field is drawn in the theme's disabled text colour, takes no focus and has no button to show its text.

With readOnly = true the field keeps its fill: it can be focused, and its text shown with the eye button, but it cannot be changed.

PantrixFilledSecureTextField(
    state = rememberTextFieldState("unchanging"),
    modifier = Modifier.fillMaxWidth(),
    enabled = false,
    label = "App password",
    supportingText = "Set by your organisation",
    tagKey = "managed_password"
)
PantrixFilledSecureTextField(
    state = rememberTextFieldState("PX-7730-1184"),
    modifier = Modifier.fillMaxWidth(),
    readOnly = true,
    label = "Backup code",
    supportingText = "Shown with the eye button, cannot be changed",
    tagKey = "backup_code"
)

Its own colours and style

The filled secure field takes the filled text field's FilledTextFieldColors and FilledTextFieldStyle: the two filled fields are restyled together.

The first field's fill, label, text, icon, outline and caret are from the app's own purple; the eye button is drawn in the icon colour. What is not given, such as the fill with the focus, stays the theme's role. The second's box is fully round: FilledTextFieldStyle(shape = ShapeRole.Full).

val own = ownColors()
PantrixFilledSecureTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Membership password",
    colors = FilledTextFieldColors(
        container = own.container,
        focusedOutline = own.color,
        text = own.onContainer,
        label = own.onContainer,
        icon = own.onContainer,
        cursor = own.color
    ),
    tagKey = "own_colors"
)
PantrixFilledSecureTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Archive password",
    style = FilledTextFieldStyle(shape = ShapeRole.Full),
    tagKey = "pill"
)

API

state

A secure text field whose label is inside its box: a password, a PIN or a card's security code in the filled box of PantrixFilledTextField.

field

A filled secure text field bound to a form's field: its text, its error and its name come from field.

FilledTextFieldStyle

PantrixFilledTextField's box: its shape, how tall and how wide it is at the least, the room around what it holds, its icons and its outline.

FilledTextFieldColors

What PantrixFilledTextField is painted with, for a field that does not take the theme's: a colour that is set is used, and one that is left out stays the theme's role. A product gives the colours it changes and no others:

Accessibility

• Keyboard and autofill. What keyboardOptions leaves unset is a password's: the password keyboard and no corrections. Without a contentType the field holds ContentType.Password.