Filled Text Area

A filled text area: a field for text of several lines, a comment, a message or a note, on a filled box that grows with what is typed and then scrolls, with its label inside the box, and help or an error's message below it and a count of its characters.

import com.pantrixui.components.inputs.filledtextarea.PantrixFilledTextArea

• Three overloads. The one that takes a state keeps the text in a TextFieldState. The one that takes a value and an onValueChange keeps the text in its caller; the text field underneath does not tell how far it is scrolled, so its box has no bar. The one that takes a field takes its value, its error and its name from the form's field.
• Lines. minLines (3 by default) says how many lines the box is at the least, and maxLines (8 by default) at the most. A Modifier.height given to the field takes the place of the lines, and the text scrolls inside the box.
• Enter is a new line. The keyboard's action key is always the new line. Sending is onSubmit's: Ctrl+Enter or Cmd+Enter on a hardware keyboard. Tab moves the focus on and types no tab.
• A soft limit. maxLength can be passed (TextLimit.Allow): past it the count says how far past in words ("12 over the limit"), and the count and the outline turn to the error's colour. A form is not submitted with a bound field's text past the limit. TextLimit.Block turns an edit past the limit down whole. A screen reader is told the count once typing stops, at the limit and past it.
• Icons and the clear button. leadingIcon, trailingIcon and showClearButton stand at the first line.
• The handle that resizes. On a desktop and on the web the handle in the box's bottom corner drags the box taller and shorter; a phone has no handle. resizable = false takes the handle away.
• Style, colours and direction. style (FilledTextFieldStyle) and colors (FilledTextFieldColors) are the filled text field's. In a right-to-left layout the handle is in the bottom corner at the left.

Examples

A comment that grows

A comment field: three lines while it is empty, with its label resting in the first line's place; a press on the field raises the label above the text, and the placeholder shows. As it is typed in the box grows a line at a time, and at eight lines the text scrolls inside the box. A sentence starts with a capital: the keyboard opens that way.

maxLength = 500 writes the count under the box. The line below reads comment.text as it is typed.

val comment = rememberTextFieldState()
PantrixFilledTextArea(
    state = comment,
    modifier = Modifier.fillMaxWidth(),
    label = "Comment",
    placeholder = "What did you think of the product?",
    supportingText = "Your comment is public",
    maxLength = 500,
    tagKey = "filled_comment"
)
PantrixText(
    text = "Lines: ${comment.text.lines().size}",
    color = PantrixTheme.colors.textSecondary
)

A field given a height

A height given to the field is the whole field's: Modifier.height(200.dp). The box fills what the count leaves of it; that height takes the place of the lines, and a text that does not fit scrolls inside the box.

The second field is given heightIn: the handle drags the box only within that range. A fixed height leaves the handle nothing to move.

PantrixFilledTextArea(
    state = rememberTextFieldState(DELIVERY_NOTES),
    modifier = Modifier.fillMaxWidth().height(200.dp),
    label = "Delivery instructions",
    showClearButton = true,
    maxLength = 400,
    tagKey = "filled_instructions"
)
PantrixFilledTextArea(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth().heightIn(max = 320.dp),
    label = "Extra note",
    supportingText = "The handle makes it 320dp tall at the most",
    tagKey = "filled_extra_note"
)

private const val DELIVERY_NOTES =
    "Use the back door of the building; the bell on the front door does not work. The lift is serviced on Fridays, " +
        "take the stairs to the third floor. If I am out, leave the parcel with the porter, Mr Hasan. Thank you!"

A soft limit and the count

The limit is soft: the text may pass 140 characters. Past it the count says how far past in words ("6 over the limit"), the count and the outline turn to the error's colour, and a screen reader is told the field's error, "Too long". Paste a long text: it is taken whole, and you can cut it where you choose.

Type and stop with a screen reader on: the count is told once, after typing stops.

PantrixFilledTextArea(
    state = rememberTextFieldState(ALMOST_A_POST),
    modifier = Modifier.fillMaxWidth(),
    label = "Post",
    supportingText = "140 characters at the most",
    minLines = 2,
    maxLength = 140,
    // The default: the text may pass the limit.
    overLimit = TextLimit.Allow,
    tagKey = "filled_post"
)

private const val ALMOST_A_POST =
    "The new version is out! A dark theme, faster search and an offline mode are here. Tell us what you think; " +
        "your comments guide us."

A limit that blocks, on a field whose text is a String

overLimit = TextLimit.Block turns down an edit past the limit whole: typing stops at the limit, and a paste that does not fit is not put in at all.

This field holds its text as a String: value and onValueChange. An edit past the limit is never asked of onValueChange. The text field underneath does not tell how far it is scrolled, so this overload's box has no bar.

var reason by remember { mutableStateOf("") }
PantrixFilledTextArea(
    value = reason,
    onValueChange = { reason = it },
    modifier = Modifier.fillMaxWidth(),
    label = "Reason for the return",
    placeholder = "In a few words",
    minLines = 2,
    maxLines = 4,
    maxLength = 80,
    overLimit = TextLimit.Block,
    tagKey = "filled_return_reason"
)

Sending with Ctrl/Cmd+Enter

onSubmit is called by Ctrl+Enter or Cmd+Enter on a hardware keyboard; Enter alone starts a new line. A software keyboard has no such keys, so a "Send" button stands beside it as well. Type a message and press Ctrl+Enter: the app's snackbar says the message was sent, and the field is emptied.

The send is reported as an event (submit); what was typed never is.

val snackbars = LocalPantrixSnackbars.current
val scope = rememberCoroutineScope()
val message = rememberTextFieldState()
val send = {
    if (message.text.isNotBlank()) {
        scope.launch { snackbars?.show(message = "Message sent", tagKey = "filled_message_sent") }
        message.clearText()
    }
}
PantrixFilledTextArea(
    state = message,
    modifier = Modifier.fillMaxWidth(),
    label = "Message",
    placeholder = "Send with Ctrl+Enter or Cmd+Enter",
    minLines = 2,
    maxLines = 6,
    onSubmit = send,
    tagKey = "filled_message"
)
PantrixButton(text = "Send", onClick = send, tagKey = "filled_send_message")

Bound to a form's field

The PantrixFilledTextArea that takes a field takes its value, its error and its name from the form's field: no tagKey is given, the field's id is the automation key (FilledTextArea_<id>). With form given, Ctrl+Enter or Cmd+Enter submits the form through the "Save" button.

The limit is soft, but the form is not submitted with a text past it: the field is in error with "Too long", the count says how far past, and the focus goes to the field. Leave the field empty, or go past 160 characters, and press "Save".

val snackbars = LocalPantrixSnackbars.current
val scope = rememberCoroutineScope()
val form = rememberFormState()
PantrixFilledTextArea(
    field = form.field("filled_bio", initial = "", Rules.notBlank("Tell us about yourself in a few sentences")),
    modifier = Modifier.fillMaxWidth(),
    form = form,
    label = "About me",
    supportingText = "Shown on your profile",
    maxLength = 160
)
PantrixButton(
    text = "Save",
    onClick = {
        scope.launch { form.submit { snackbars?.show(message = "Profile saved", tagKey = "filled_bio_saved") } }
    },
    form = form,
    tagKey = "filled_save_bio"
)

Disabled and read-only

enabled = false draws the field in the theme's disabled colours: it takes no focus, cannot be typed into, has no handle, and a screen reader is told it is disabled.

readOnly = true only stops changes: the field is focused, its text selected, copied and scrolled; it can be made taller with the handle and read.

PantrixFilledTextArea(
    state = rememberTextFieldState("Your order has shipped; no note can be added."),
    modifier = Modifier.fillMaxWidth(),
    enabled = false,
    label = "Shipping note",
    minLines = 2,
    tagKey = "filled_shipping_note"
)
PantrixFilledTextArea(
    state = rememberTextFieldState(RETURN_POLICY),
    modifier = Modifier.fillMaxWidth(),
    readOnly = true,
    label = "Return policy",
    maxLines = 4,
    tagKey = "filled_return_policy"
)

private const val RETURN_POLICY =
    "You can return the product within 14 days of the day you received it. It must be unused, with its labels " +
        "still on and in its original packaging. We pay for the return shipping. Your money goes back to the card you " +
        "paid with within 3 working days of the product reaching our warehouse."

Its own colours and style

colors and style are the filled text field's: FilledTextFieldColors and FilledTextFieldStyle. The colours that are given are used, and the rest stay the theme's roles. The first field's outline with the focus, its caret and its scroll bar are the app's own purple; the handle and the clear button take the icon's colour.

The second field's style draws the box rounder with ShapeRole.Large and gives it more padding.

val own = ownColors()
PantrixFilledTextArea(
    state = rememberTextFieldState(DELIVERY_NOTES),
    modifier = Modifier.fillMaxWidth(),
    label = "Note",
    showClearButton = true,
    maxLines = 4,
    colors = FilledTextFieldColors(
        focusedOutline = own.color,
        cursor = own.color,
        icon = own.color,
        scrollBar = own.color
    ),
    tagKey = "filled_own_colors"
)
PantrixFilledTextArea(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Description",
    style = FilledTextFieldStyle(shape = ShapeRole.Large, horizontalPadding = 20.dp, verticalPadding = 16.dp),
    tagKey = "filled_own_style"
)

private const val DELIVERY_NOTES =
    "Use the back door of the building; the bell on the front door does not work. The lift is serviced on Fridays, " +
        "take the stairs to the third floor. If I am out, leave the parcel with the porter, Mr Hasan. Thank you!"

The handle that resizes

On a desktop and on the web, drag the handle in the box's bottom corner: the box gets taller or shorter, and the pointer turns to an up-and-down resize arrow. A dragged box keeps that height and does not grow with its text; nor is it ever shorter than its least lines. A phone has no handle.

The second field has resizable = false: no handle, and the box grows with its text alone.

PantrixFilledTextArea(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Meeting notes",
    supportingText = "Make it taller with the handle in the bottom corner",
    tagKey = "filled_meeting_notes"
)
PantrixFilledTextArea(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Short note",
    minLines = 2,
    maxLines = 4,
    resizable = false,
    tagKey = "filled_short_note"
)

Right to left

In a right-to-left layout the icon and the clear button swap places, the handle moves to the bottom corner at the left, and the scroll bar stands at the box's left: that is where a line ends. Each paragraph takes its direction from its own first letter.

CompositionLocalProvider(LocalLayoutDirection provides LayoutDirection.Rtl) {
    PantrixFilledTextArea(
        state = rememberTextFieldState(ARABIC_NOTE),
        modifier = Modifier.fillMaxWidth(),
        label = "ملاحظة",
        leadingIcon = {
            PantrixIcon(
                imageVector = PantrixIcons.Person,
                contentDescription = null,
                size = PantrixTheme.style(FilledTextFieldStyle).iconSize
            )
        },
        showClearButton = true,
        maxLines = 3,
        maxLength = 200,
        tagKey = "filled_arabic_note"
    )
}

private const val ARABIC_NOTE = "يرجى ترك الطرد عند البواب إذا لم أكن في المنزل. شكراً لكم!"

API

state

A filled text area: a field for text of several lines, a comment, a message or a note, on a filled box that grows with what is typed and then scrolls, with its label inside the box, and help or an error's message below it and a count of its characters.

value

A text area 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 text area 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: