Text Area

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

import com.pantrixui.components.inputs.textarea.PantrixTextArea

• 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: on Android another action would take the place of the key for a new line. Sending is onSubmit's: Ctrl+Enter or Cmd+Enter on a hardware keyboard. A software keyboard has no such keys; the screen gives a send button as well. 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 border turn to the error's colour. A paste that does not fit is taken whole, and the user cuts it where they choose. A form is not submitted with a bound field's text past the limit. TextLimit.Block turns an edit past the limit down whole, as a text field's limit does.
• Icons and the clear button. leadingIcon, trailingIcon and showClearButton stand at the first line, not in the middle of the box.
• The handle that resizes. On the platforms used with a pointer, a desktop and the web, the handle in the box's bottom corner drags the box taller and shorter. A dragged box does not grow with its text, and is never shorter than its least lines. A phone has no handle: a finger on the box scrolls the text. resizable = false takes the handle away.
• Style, colours and direction. style (TextFieldStyle) and colors (TextFieldColors) are the text field's; the handle takes the icon's colour and the bar the scrollBar colour. 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, it grows a line at a time as it is typed in, and at eight lines the text scrolls inside the box. The thin bar at the box's end shows how far the text is scrolled. 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()
PantrixTextArea(
    state = comment,
    modifier = Modifier.fillMaxWidth(),
    label = "Comment",
    placeholder = "What did you think of the product?",
    supportingText = "Your comment is public",
    maxLength = 500,
    tagKey = "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 label and the count leave 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.

PantrixTextArea(
    state = rememberTextFieldState(DELIVERY_NOTES),
    modifier = Modifier.fillMaxWidth().height(200.dp),
    label = "Delivery instructions",
    showClearButton = true,
    maxLength = 400,
    tagKey = "instructions"
)
PantrixTextArea(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth().heightIn(max = 320.dp),
    label = "Extra note",
    supportingText = "The handle makes it 320dp tall at the most",
    tagKey = "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 border 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.

PantrixTextArea(
    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 = "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("") }
PantrixTextArea(
    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 = "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 = "message_sent") }
        message.clearText()
    }
}
PantrixTextArea(
    state = message,
    modifier = Modifier.fillMaxWidth(),
    label = "Message",
    placeholder = "Send with Ctrl+Enter or Cmd+Enter",
    minLines = 2,
    maxLines = 6,
    onSubmit = send,
    tagKey = "message"
)
PantrixButton(text = "Send", onClick = send, tagKey = "send_message")

Bound to a form's field

The PantrixTextArea 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 (TextArea_<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()
PantrixTextArea(
    field = form.field("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 = "bio_saved") } }
    },
    form = form,
    tagKey = "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.

PantrixTextArea(
    state = rememberTextFieldState("Your order has shipped; no note can be added."),
    modifier = Modifier.fillMaxWidth(),
    enabled = false,
    label = "Shipping note",
    minLines = 2,
    tagKey = "shipping_note"
)
PantrixTextArea(
    state = rememberTextFieldState(RETURN_POLICY),
    modifier = Modifier.fillMaxWidth(),
    readOnly = true,
    label = "Return policy",
    maxLines = 4,
    tagKey = "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 text field's: TextFieldColors and TextFieldStyle. The colours that are given are used, and the rest stay the theme's roles. The first field's border, caret and 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()
PantrixTextArea(
    state = rememberTextFieldState(DELIVERY_NOTES),
    modifier = Modifier.fillMaxWidth(),
    label = "Note",
    showClearButton = true,
    maxLines = 4,
    colors = TextFieldColors(
        focusedBorder = own.color,
        cursor = own.color,
        icon = own.color,
        scrollBar = own.color
    ),
    tagKey = "own_colors"
)
PantrixTextArea(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Description",
    style = TextFieldStyle(shape = ShapeRole.Large, horizontalPadding = 20.dp, verticalPadding = 16.dp),
    tagKey = "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.

PantrixTextArea(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Meeting notes",
    supportingText = "Make it taller with the handle in the bottom corner",
    tagKey = "meeting_notes"
)
PantrixTextArea(
    state = rememberTextFieldState(),
    modifier = Modifier.fillMaxWidth(),
    label = "Short note",
    minLines = 2,
    maxLines = 4,
    resizable = false,
    tagKey = "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) {
    PantrixTextArea(
        state = rememberTextFieldState(ARABIC_NOTE),
        modifier = Modifier.fillMaxWidth(),
        label = "ملاحظة",
        leadingIcon = {
            PantrixIcon(
                imageVector = PantrixIcons.Person,
                contentDescription = null,
                size = PantrixTheme.style(TextFieldStyle).iconSize
            )
        },
        showClearButton = true,
        maxLines = 3,
        maxLength = 200,
        tagKey = "arabic_note"
    )
}

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

A tap outside puts the keyboard away

On iOS the keyboard of a field of several lines has no key that puts it away. Modifier.clearFocusOnTap() clears the focus when an empty part of this column is tapped, and the keyboard goes. A tap on the field or on a button is theirs: the caret moves, the button does its work. A scroll is no tap.

The app's root does the same: in this catalogue a tap on any empty part of the page puts the keyboard away.

Column(
    modifier = Modifier.fillMaxWidth().clearFocusOnTap(),
    verticalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)
) {
    PantrixTextArea(
        state = rememberTextFieldState(),
        modifier = Modifier.fillMaxWidth(),
        label = "Feedback",
        minLines = 2,
        tagKey = "feedback"
    )
    PantrixText(
        text = "Tap here to put the keyboard away",
        color = PantrixTheme.colors.textSecondary
    )
}

API

state

A text area: a field for text of several lines, a comment, a message or a note, that grows with what is typed and then scrolls, under a label, with 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.

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

• The count and a screen reader. Up to the limit the count writes "120/500". A screen reader is told it once typing stops, at the limit and past it: told at every key, it would talk over the keyboard's own echo of each letter.
• Putting the keyboard away. On iOS the keyboard of a field of several lines has no key that puts it away. Modifier.clearFocusOnTap() on the screen's root clears the focus on a tap outside the field, and the keyboard goes; this catalogue does so too.