Secure Text Field

A text field for what is not to be read over a shoulder: a password, a PIN, a card's security code.

import com.pantrixui.components.inputs.securetextfield.PantrixSecureTextField

• 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. The eye at the box's end shows the text and hides it again. A press on it with the mouse leaves the caret where it is. With a keyboard it is a Tab stop of its own, after the field, while the keyboard's "Next" key goes past it to the next field. showRevealButton = false removes the button.
• That the text was shown is not saved. When the field is composed anew, as it is when the screen turns, the text is hidden again.
• Obfuscation mode. textObfuscationMode says how the hidden text is drawn: as the platform does it, with the last character typed showing for a moment, or with nothing showing. textObfuscationCharacter is the character drawn in place of the dot.
• Autofill. If no contentType is given the field holds ContentType.Password; ContentType.NewPassword is a password that is being chosen.
• Reading the text. The text is read from the state: state.text at the moment it is used, snapshotFlow to follow it as it is typed. A caller that keeps the text as a String is handed each change that way.
• Form. The overload that takes a field gets its value, its error and its name from its field in the form. The field is checked when the focus leaves the field and its buttons; if form is given, the keyboard's action key submits the form.
• What comes from the text field. label, placeholder, supportingText, error, leadingIcon, showClearButton and maxLength are as they are in the text field. trailingIcon stands after the clear button and the reveal button.
• Automation. With tagKey the field is named SecureTextField_<tagKey>, the clear button SecureTextFieldClear_<tagKey> and the reveal button SecureTextFieldReveal_<tagKey>. The field reports that it took the focus, that it was cleared and that its text was shown or hidden; never its text.

Examples

At its plainest

The least there is to write: a TextFieldState and a label. What is typed is drawn as dots; it cannot be cut or copied. The text is in the state: the line below reads only the length of password.text.

The eye button at the box's end shows the text and hides it again. A press on it with the mouse does not take the caret out of the field. With a keyboard, Tab stops at the button after the field, while the keyboard's "Next" key skips the button. That the text was shown is not saved: when the field is composed anew it is hidden again.

val password = rememberTextFieldState()
PantrixSecureTextField(
    state = password,
    modifier = Modifier.fillMaxWidth(),
    label = "Wi-Fi password",
    tagKey = "wifi_password"
)
PantrixText(text = "Characters typed: ${password.text.length}", color = PantrixTheme.colors.textSecondary)

Obfuscation mode and character

textObfuscationMode says how the text is drawn while it is hidden. The default, System, does as the platform does: on Android the last character typed shows for a moment where the system's own setting says so, and nowhere else does anything show. RevealLastTyped shows the last character typed for a moment on every platform, and Hidden shows it on none. Type something into the first two fields and see the difference.

textObfuscationCharacter is what is drawn in place of a hidden character: in the third field, stars instead of dots.

PantrixSecureTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "The last character typed shows",
    textObfuscationMode = TextObfuscationMode.RevealLastTyped,
    tagKey = "reveal_last"
)
PantrixSecureTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Nothing shows",
    textObfuscationMode = TextObfuscationMode.Hidden,
    tagKey = "hidden"
)
PantrixSecureTextField(
    state = rememberTextFieldState("stars"),
    modifier = Modifier.fillMaxWidth(),
    label = "Stars instead of dots",
    textObfuscationCharacter = '*',
    tagKey = "stars"
)

Supporting text and error

supportingText stands under the box. error = true turns the border, the label, the supporting text and the caret to the danger role, and the message is announced to a screen reader as the error. Type different things into the two fields: the second one goes into error and says what is wrong.

Each field's text is in its own state; the comparison reads both from there. The first field was given only an action key: the keyboard's "Next" key does not stop at the eye button, and goes on to the second field. The rest of the keyboard was not given, so it is a password's: the password keyboard and no corrections.

val password = rememberTextFieldState()
val repeated = rememberTextFieldState()
val differs = repeated.text.isNotEmpty() && repeated.text.toString() != password.text.toString()
PantrixSecureTextField(
    state = password,
    modifier = Modifier.fillMaxWidth(),
    label = "Account password",
    supportingText = "Include letters and digits",
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
    contentType = ContentType.NewPassword,
    tagKey = "chosen_password"
)
PantrixSecureTextField(
    state = repeated,
    modifier = Modifier.fillMaxWidth(),
    label = "Account password (again)",
    supportingText = if (differs) "The two passwords do not match" else "Type the same password once more",
    error = differs,
    contentType = ContentType.NewPassword,
    tagKey = "repeated_password"
)

Clear button, count and icon

Three things can stand side by side at the box's end, always in the same order: the clear button, the button that shows the text, and trailingIcon. The icon here says whether the password is long enough; it is not decoration, so it has a contentDescription.

The clear button of showClearButton shows while the field is not empty, and leaves the caret in the field. maxLength = 32 does not take a longer password; the count is written under the box, opposite the supporting text. placeholder shows only while the field is empty.

val password = rememberTextFieldState()
val longEnough = password.text.length >= 12
PantrixSecureTextField(
    state = password,
    modifier = Modifier.fillMaxWidth(),
    label = "Master password",
    placeholder = "It can be a sentence too",
    supportingText = "At least 12 characters",
    trailingIcon = {
        PantrixIcon(
            imageVector = if (longEnough) PantrixIcons.Success else PantrixIcons.Warning,
            contentDescription = if (longEnough) "Long enough" else "Still too short",
            size = PantrixTheme.style(TextFieldStyle).iconSize
        )
    },
    showClearButton = true,
    maxLength = 32,
    tagKey = "master_password"
)

A sign-in bound to a form

The PantrixSecureTextField that takes a field gets its value, its error and its name from its field in the form: if the field is left with the password too short, the rule's message takes the place of the supporting text. When the focus moves to the eye button the field does not count as left, so the error does not show then. The text of a field bound to a form is the value of the form's field: it does not have to be taken separately.

In a field given form, the keyboard's action key submits the form through the "Sign in" button; in the email field the "Next" key moves the focus to the password. The email field is a PantrixTextField: the two components draw the same label and the same box.

val snackbars = LocalPantrixSnackbars.current
val scope = rememberCoroutineScope()
val form = rememberFormState()
PantrixTextField(
    field = form.field("login_email", initial = "", Rules.matches(EMAIL, "Enter a valid email address")),
    modifier = Modifier.fillMaxWidth(),
    form = form,
    label = "Email",
    placeholder = "name@example.com",
    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Email, imeAction = ImeAction.Next),
    contentType = ContentType.EmailAddress
)
PantrixSecureTextField(
    field = form.field("login_password", initial = "", Rules.minLength(8, "The password must be at least 8 characters long")),
    modifier = Modifier.fillMaxWidth(),
    form = form,
    label = "Password",
    supportingText = "At least 8 characters",
    showClearButton = true
)
PantrixButton(
    text = "Sign in",
    onClick = {
        scope.launch { form.submit { snackbars?.show(message = "Signed in", tagKey = "signed_in") } }
    },
    form = form,
    tagKey = "sign_in"
)

private val EMAIL = Regex("""\S+@\S+\.\S+""")

A form that carries its text to a ViewModel

Each field builds its state with rememberTextFieldState, from the value the ViewModel holds at that moment; it follows the text in the state with snapshotFlow and reports each change to the ViewModel. This is how the text is taken from a field's state: the same way in a plain text field and in a secure one.

The first value in the ViewModel is read once. From then on it is one way: the text flows from the field to the ViewModel, and a change made in the ViewModel does not come back to the field. When the screen is composed anew the ViewModel is still there, and the fields start from its value.

The line below shows what the ViewModel holds: the username, and the length of the password rather than the password itself. The button reads from it too: it cannot be pressed until there is a username and a long enough password.

val viewModel = viewModel(key = "account") { AccountViewModel() }
val snackbars = LocalPantrixSnackbars.current
val scope = rememberCoroutineScope()
val initialUiState = remember(viewModel) { viewModel.uiState.value }
val uiState by viewModel.uiState.collectAsStateWithLifecycle()

val username = rememberTextFieldState(initialUiState.username)
LaunchedEffect(username) {
    snapshotFlow { username.text.toString() }.collectLatest { viewModel.updateUsername(it) }
}
PantrixTextField(
    state = username,
    modifier = Modifier.fillMaxWidth(),
    label = "Username",
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
    contentType = ContentType.NewUsername,
    tagKey = "account_username"
)

val password = rememberTextFieldState(initialUiState.password)
LaunchedEffect(password) {
    snapshotFlow { password.text.toString() }.collectLatest { viewModel.updatePassword(it) }
}
PantrixSecureTextField(
    state = password,
    modifier = Modifier.fillMaxWidth(),
    label = "New password",
    supportingText = "At least 8 characters",
    contentType = ContentType.NewPassword,
    tagKey = "account_password"
)

PantrixText(
    text = "ViewModel: username \"${uiState.username}\", password length ${uiState.password.length}",
    style = PantrixTheme.typography.footnote,
    color = PantrixTheme.colors.textSecondary,
    tagKey = "account_state"
)
PantrixButton(
    text = "Create account",
    onClick = {
        scope.launch {
            snackbars?.show(message = "Account created for ${uiState.username}", tagKey = "account_created")
        }
    },
    enabled = uiState.isComplete,
    tagKey = "create_account"
)

private class AccountViewModel : ViewModel() {
    private val state = MutableStateFlow(AccountUiState())
    val uiState: StateFlow<AccountUiState> = state.asStateFlow()

    fun updateUsername(username: String) {
        state.update { it.copy(username = username) }
    }

    fun updatePassword(password: String) {
        state.update { it.copy(password = password) }
    }
}

private data class AccountUiState(
    val username: String = "",
    val password: String = ""
) {
    val isComplete: Boolean get() = username.isNotBlank() && password.length >= 8
}

A PIN that gives its text as a String

The secure field has no overload that takes value and onValueChange; for a caller that keeps its text as a String, one is built on top of the state. PinInput starts the field with value, follows the text in the state with snapshotFlow and reports each change through onValueChange. The flow is one way: value is the first value, and if it is changed from outside later, the field does not show the change. The supporting text is made from the String the caller holds, and says how many digits are missing.

This is a PIN: with showRevealButton = false it has no button to show its text, and with TextObfuscationMode.Hidden the last digit typed is not shown either. Its keyboard is the number keyboard (KeyboardType.NumberPassword); an input transformation turns down whatever is not a digit.

var pin by remember { mutableStateOf("") }
PinInput(
    value = pin,
    onValueChange = { pin = it },
    label = "PIN",
    supportingText = if (pin.length == 6) "PIN complete" else "Digits left: ${6 - pin.length}",
    modifier = Modifier.fillMaxWidth()
)

@Composable
private fun PinInput(
    value: String,
    onValueChange: (String) -> Unit,
    label: String,
    supportingText: String,
    modifier: Modifier = Modifier
) {
    val state = rememberTextFieldState(value)
    val latestOnValueChange by rememberUpdatedState(onValueChange)
    LaunchedEffect(state) {
        snapshotFlow { state.text.toString() }.collect { latestOnValueChange(it) }
    }
    PantrixSecureTextField(
        state = state,
        modifier = modifier,
        label = label,
        supportingText = supportingText,
        showRevealButton = false,
        maxLength = 6,
        textObfuscationMode = TextObfuscationMode.Hidden,
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.NumberPassword),
        inputTransformation = DigitsOnly,
        tagKey = "pin"
    )
}

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

Disabled and read-only

A field with enabled = false takes no focus, is drawn in the theme's disabled colours and has no button to show its text.

A field with readOnly = true can be focused and its text can be shown with the button, but it cannot be changed: like a recovery code that is given once.

PantrixSecureTextField(
    state = rememberTextFieldState("unchanging"),
    modifier = Modifier.fillMaxWidth(),
    enabled = false,
    label = "Disabled",
    supportingText = "It has no button to show its text",
    tagKey = "locked_password"
)
PantrixSecureTextField(
    state = rememberTextFieldState("PX-4821-9930"),
    modifier = Modifier.fillMaxWidth(),
    readOnly = true,
    label = "Recovery code",
    supportingText = "Read-only: it can be shown but not changed",
    tagKey = "recovery_code"
)

Its own colours and style

The secure field has no style class or colour class of its own: it takes the TextFieldColors and the TextFieldStyle of PantrixTextField. A product that restyles its text fields in the theme restyles its password fields with them.

In the first field the focused border, the caret and the icon colour are the app's own purple: the eye button is drawn in the icon colour too. The colours that are not given keep their role in the theme. The second field's box is fully round: TextFieldStyle(shape = ShapeRole.Full).

val own = ownColors()
PantrixSecureTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Wallet password",
    colors = TextFieldColors(focusedBorder = own.color, icon = own.color, cursor = own.color),
    tagKey = "own_colors"
)
PantrixSecureTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Vault password",
    style = TextFieldStyle(shape = ShapeRole.Full),
    tagKey = "pill"
)

API

state

A text field for what is not to be read over a shoulder: a password, a PIN, a card's security code.

field

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

TextFieldStyle

PantrixTextField's box: its shape, how tall and how wide it is at the least, the room around its text, its icons and its border.

TextFieldColors

What PantrixTextField 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. What keyboardOptions leaves unset is a password's: the password keyboard and no corrections. Naming an action key and nothing else does not bring back a keyboard that learns what is typed. KeyboardType.NumberPassword is a PIN's.