Filled Text Field

A text field whose label is inside its box: the label rests where the text will be, and moves up to its own line above the text when the field takes the focus or holds a text.

import com.pantrixui.components.inputs.filledtextfield.PantrixFilledTextField

• The label inside the box. At rest label is in the text's place and in the text's size; with the focus, or while there is a text, it shrinks and moves up to its own line. In a field with no label the text stands in the middle of the box.
• Placeholder. placeholder shows while the label is out of its place: while the field is empty and has the focus. In a field with no label it shows whenever the field is empty.
• Fill and outline. At rest the box is filled and has no outline. With the focus and in error the fill turns to the surface's colour and the box is outlined; it takes an outline under a pointer too. A disabled field has no fill.
• Supporting text and error. supportingText is written under the box. error turns the outline, the supporting text and the caret to the danger role, and a screen reader is told; the label keeps its own colour.
• Several lines. With lineLimits = TextFieldLineLimits.MultiLine(...) the box is as tall as its least lines, grows to its most, and from there scrolls its text inside it: the bar at its end shows how far.
• Icons, clear button, count. leadingIcon stands before the label and the text, and trailingIcon after them. showClearButton shows the button that empties the field; maxLength limits the length and writes the count.
• Three overloads. In the one that takes state the text is read from the state. The one that takes value and onValueChange keeps the text with its caller; it has no scroll bar. The one that takes field takes its value, its error and its name from its field in the form.
• Style and colours. style (FilledTextFieldStyle) changes the box's shape and dimensions, and colors (FilledTextFieldColors) its colours: only the fields that are set. A disabled field has no fill and is in the theme's disabled text colour whatever is given.
• Text size. What is typed, the resting label and the placeholder are set in the style's textRole: body (16sp) on Android and iOS, label (14sp) on the desktop and the web.
• Automation. With tagKey the field is named FilledTextField_<tagKey>, and its clear button FilledTextFieldClear_<tagKey>. The field reports that it took the focus and that it was cleared, and never its text.

Examples

At its plainest

The least it takes: a TextFieldState and a label. The label is inside the box: it rests in the text's place while the field is empty and without the focus. Press the field: the label moves up to its own line above the text and makes room for the text. If the focus leaves the field while it is empty, the label goes back to its place.

The typed text is read from the state: the line below shows city.text as it is typed.

val city = rememberTextFieldState()
PantrixFilledTextField(
    state = city,
    modifier = Modifier.fillMaxWidth(),
    label = "City",
    tagKey = "city"
)
PantrixText(
    text = if (city.text.isEmpty()) "No city typed yet" else "Typed: ${city.text}",
    color = PantrixTheme.colors.textSecondary
)

Label and placeholder

The first field is empty: the label rests in the text's place and the placeholder is not shown. Press the field: the label moves up, and the placeholder appears where the label was. A placeholder is not a label; it gives an example of what to type.

The second field holds a text, so its label is always up. The third has no label: the text stands in the middle of the box, the placeholder shows whenever the field is empty, and contentDescription tells a screen reader the field's name.

PantrixFilledTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Website",
    placeholder = "https://example.com",
    tagKey = "website"
)
PantrixFilledTextField(
    state = rememberTextFieldState("Kadıköy"),
    modifier = Modifier.fillMaxWidth(),
    label = "District",
    tagKey = "district"
)
PantrixFilledTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    placeholder = "Search neighbourhoods",
    contentDescription = "Search neighbourhoods",
    tagKey = "neighbourhood"
)

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 outline and the message are what show the error. The fill turns to the surface's colour, as it does with the focus.

The field starts in error. Delete the space: the outline loses the error's colour and the supporting text takes the place of the error message.

val username = rememberTextFieldState("ayşe yılmaz")
val hasSpace = username.text.contains(' ')
PantrixFilledTextField(
    state = username,
    modifier = Modifier.fillMaxWidth(),
    label = "Username",
    supportingText = if (hasSpace) "A username cannot contain spaces" else "Appears in your profile's address",
    error = hasSpace,
    showClearButton = true,
    tagKey = "username"
)

Icon, clear button and action key

leadingIcon stands before the label and the text. A slot does not size what is put in it; the icon takes the size in the filled field's style: PantrixTheme.style(FilledTextFieldStyle).iconSize. While the field is not empty, showClearButton shows the button that empties it: the button leaves the caret in the field, and is no stop for Tab.

keyboardOptions makes the keyboard's action key "Search"; onKeyboardAction is called when that key is pressed. Type something and press the keyboard's "Search" key or Enter: the app's snackbar says what was searched for.

val snackbars = LocalPantrixSnackbars.current
val scope = rememberCoroutineScope()
val query = rememberTextFieldState()
PantrixFilledTextField(
    state = query,
    modifier = Modifier.fillMaxWidth(),
    label = "Search branches",
    leadingIcon = {
        PantrixIcon(
            imageVector = PantrixIcons.Search,
            contentDescription = null,
            size = PantrixTheme.style(FilledTextFieldStyle).iconSize
        )
    },
    showClearButton = true,
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search),
    onKeyboardAction = { scope.launch { snackbars?.show(message = "Branch searched for: ${query.text}") } },
    tagKey = "branch"
)

Input and output transformations

inputTransformation turns an edit down whole if it holds anything that is not a digit; maxLength = 4 applies to what it lets through. outputTransformation draws a slash between the month and the year: the slash is not part of the text.

Type "1228": the box shows "12/28", while expiry.text, which the line below reads, is four digits.

val expiry = rememberTextFieldState()
PantrixFilledTextField(
    state = expiry,
    modifier = Modifier.fillMaxWidth(),
    label = "Expiry date",
    placeholder = "MM/YY",
    maxLength = 4,
    showCharacterCount = false,
    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
    inputTransformation = DigitsOnly,
    outputTransformation = MonthSlashYear,
    contentType = ContentType.CreditCardExpirationDate,
    tagKey = "expiry"
)
PantrixText(text = "Text held: \"${expiry.text}\"", color = PantrixTheme.colors.textSecondary)

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

private val MonthSlashYear = OutputTransformation {
    if (length > 2) insert(2, "/")
}

A money transfer form

A money transfer form, with the three overloads together. The first two fields are bound to the form: each takes its value, its error and its name from its field in the form; if the focus leaves one while it is empty, the rule's message shows under the box and the box is outlined in the error colour. The amount field holds its text as a String and turns down whatever is not a digit in onValueChange: an edit that is turned down is not shown. Its limit is seven digits; its count is hidden with showCharacterCount = false.

The note is three lines tall: a text that does not fit scrolls inside the box, and the bar at its end shows how far. Its text is in the state created with rememberTextFieldState, and is read from there when the form is sent: the notification reads it with note.text.

In the first three fields the keyboard's "Next" key moves the focus to the next field. Leave the fields empty and press "Send": the form is not sent, and the first field in error takes the focus.

val snackbars = LocalPantrixSnackbars.current
val scope = rememberCoroutineScope()
val form = rememberFormState()
var amount by rememberSaveable { mutableStateOf("") }
val note = rememberTextFieldState()
PantrixFilledTextField(
    field = form.field("recipient", initial = "", Rules.notBlank("Enter the recipient's name")),
    modifier = Modifier.fillMaxWidth(),
    form = form,
    label = "Recipient's full name",
    keyboardOptions = KeyboardOptions(capitalization = KeyboardCapitalization.Words, imeAction = ImeAction.Next)
)
PantrixFilledTextField(
    field = form.field("iban", initial = "", Rules.notBlank("Enter the IBAN")),
    modifier = Modifier.fillMaxWidth(),
    form = form,
    label = "IBAN",
    placeholder = "TR00 0000 0000 0000 0000 0000 00",
    showClearButton = true,
    keyboardOptions = KeyboardOptions(
        capitalization = KeyboardCapitalization.Characters,
        imeAction = ImeAction.Next
    )
)
PantrixFilledTextField(
    value = amount,
    onValueChange = { if (it.all(Char::isDigit)) amount = it },
    modifier = Modifier.fillMaxWidth(),
    label = "Amount",
    placeholder = "0",
    supportingText = "Digits only",
    trailingIcon = { PantrixText(text = "TL") },
    maxLength = 7,
    showCharacterCount = false,
    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number, imeAction = ImeAction.Next),
    tagKey = "amount"
)
PantrixFilledTextField(
    state = note,
    modifier = Modifier.fillMaxWidth(),
    label = "Note",
    placeholder = "Rent, dues, debt…",
    maxLength = 140,
    lineLimits = TextFieldLineLimits.MultiLine(minHeightInLines = 3, maxHeightInLines = 3),
    tagKey = "transfer_note"
)
PantrixButton(
    text = "Send",
    onClick = {
        scope.launch {
            form.submit {
                // The note is read from the state at the moment it is used.
                val sent = if (note.text.isBlank()) "Money sent" else "Money sent: ${note.text}"
                snackbars?.show(message = sent, tagKey = "transfer_sent")
            }
        }
    },
    form = form,
    tagKey = "send_transfer"
)

A field given a height

A height given to the field is the whole field's: Modifier.height(140.dp). The box takes what the supporting text under it leaves of that height; the label and the text stay inside the box, a text that does not fit scrolls there, and the bar at its end shows how far.

PantrixFilledTextField(
    state = rememberTextFieldState(COMPLAINT),
    modifier = Modifier.fillMaxWidth().height(140.dp),
    label = "Your complaint",
    supportingText = "The field's height is fixed: the text scrolls inside the box",
    lineLimits = TextFieldLineLimits.MultiLine(),
    tagKey = "complaint"
)

private const val COMPLAINT = "The same payment was taken from my card twice.\n" +
    "The first was on the third of the month, the second on the fourth.\n" +
    "Both are for the same amount and from the same merchant.\n" +
    "I have both receipts.\n" +
    "I would like one of them refunded."

Disabled and read-only

enabled = false takes the field's fill away: a disabled field is drawn in the theme's disabled text colour on the ground it stands on, takes no focus, and a screen reader is told that it is disabled. This is so whatever colors gives: a disabled field looks the same everywhere in an app.

With readOnly = true the field keeps its fill and its colours: it can be focused and its text selected and copied; it just cannot be changed.

PantrixFilledTextField(
    state = rememberTextFieldState("TL current account - 1042"),
    modifier = Modifier.fillMaxWidth(),
    enabled = false,
    label = "Sending account",
    supportingText = "Cannot be changed in this transaction",
    tagKey = "account"
)
PantrixFilledTextField(
    state = rememberTextFieldState("TR33 0006 1005 1978 6457 8413 26"),
    modifier = Modifier.fillMaxWidth(),
    readOnly = true,
    label = "Your IBAN",
    supportingText = "Read-only: it can be selected and copied",
    tagKey = "own_iban"
)

Its own colours

The colours given with colors are used, and the ones left out stay the theme's roles. The first field takes its colours from the theme's info role. At rest the fill is the role's soft tone; the label, the text and the icon are in the colour that reads on that tone. With the focus and under a pointer the outline is the role's own colour. The fill with the focus, the placeholder, the supporting text and the error colour are not given: they stay as the theme has them.

The second field does the same with the app's own purple: a colour that is in none of the theme's roles. Press the field: the outline and the caret are purple, and with the focus the fill turns to the theme's surface colour.

val info = PantrixTheme.colors.info
PantrixFilledTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Referral code",
    placeholder = "PX-0000",
    supportingText = "The code of the person who invited you, if any",
    showClearButton = true,
    colors = FilledTextFieldColors(
        container = info.container,
        hoveredOutline = info.color,
        focusedOutline = info.color,
        text = info.onContainer,
        label = info.onContainer,
        icon = info.onContainer,
        cursor = info.color
    ),
    tagKey = "reference"
)
val own = ownColors()
PantrixFilledTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Promo code",
    colors = FilledTextFieldColors(
        container = own.container,
        hoveredOutline = own.color,
        focusedOutline = own.color,
        text = own.onContainer,
        label = own.onContainer,
        cursor = own.color
    ),
    tagKey = "own_colors"
)

Its own style

style is this call's own style: only the fields it sets change, and the rest comes from the theme's and the platform's style.

The first field's box is fully round: FilledTextFieldStyle(shape = ShapeRole.Full). The second has small corners and, with borderWidth = 2.dp, a thick outline. The outline shows with the focus, in error and under a pointer; at rest the box has none.

PantrixFilledTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Fully round box",
    style = FilledTextFieldStyle(shape = ShapeRole.Full),
    tagKey = "pill"
)
PantrixFilledTextField(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Small corners, thick outline",
    style = FilledTextFieldStyle(shape = ShapeRole.Small, borderWidth = 2.dp),
    tagKey = "small_corners"
)

API

state

A text field whose label is inside its box: the label rests where the text will be, and moves up to its own line above the text when the field takes the focus or holds a text.

value

A filled text field whose text is a String its caller holds: value is what it shows, and onValueChange is asked for every change the user makes.

field

A filled 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 transformations. keyboardOptions, onKeyboardAction, inputTransformation, outputTransformation and contentType are the same as the text field's.