TextArea

TextArea is a component that provides a multiline text input area.

The TextArea is an input control component and is often used in forms. See the Using Forms guide for details.

To add new lines to the input field press Shift + Enter.

Properties

autoFocus (default: false)

If this property is set to true, the component gets the focus automatically when displayed.

autoSize (default: false)

If set to true, this boolean property enables the TextArea to resize automatically based on the number of lines inside it.

Note: If either autoSize, maxRows or minRows is set, the rows prop has no effect.

Write multiple lines in the TextArea in the demo below to see how it resizes automatically.

<App>
  <TextArea autoSize="true" />
</App>

enabled (default: true)

This boolean property value indicates whether the component responds to user events (true) or not (false).

<App>
  <TextArea enabled="false" />
</App>

enterSubmits (default: true)

This optional boolean property indicates whether pressing the Enter key on the keyboard prompts the parent Form component to submit.

Press Enter after writing something in the TextArea in the demo below. See Using Forms for details.

<App>
  <Form onSubmit="toast.success(JSON.stringify(address.value))">
    <TextArea
      id="address"
      enterSubmits="true"
      initialValue="Suzy Queue, 4455 Landing Lange, APT 4, Louisville, KY 40018-1234" />
  </Form>
</App>

escResets (default: false)

This boolean property indicates whether the TextArea contents should be reset when pressing the ESC key.

initialValue

This property sets the component's initial value.

The initial value displayed in the input field.

<App>
  <TextArea initialValue="Example text" />
</App>

label

This property sets the label of the component.

labelBreak (default: false)

This boolean value indicates if the TextArea labels can be split into multiple lines if it would overflow the available label width.

labelPosition (default: "top")

Places the label at the given position of the component.

Available values:

labelWidth

This property sets the width of the TextArea.

maxLength

This property sets the maximum length of the input it accepts.

maxRows

This optional property sets the maximum number of text rows the TextArea can grow.

Note: If either autoSize, maxRows or minRows is set, the rows prop has no effect.

<App>
  <TextArea
    maxRows="3"
    initialValue="Lorem ipsum dolor sit amet,
    consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
    Ut enim ad minim veniam,
    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." />
</App>

minRows

This optional property sets the minimum number of text rows the TextArea can shrink.

Note: If either autoSize, maxRows or minRows is set, the rows prop has no effect.

<App>
  <TextArea minRows="3" initialValue="Lorem ipsum dolor sit amet..." />
</App>

placeholder

A placeholder text that is visible in the input field when its empty.

<App>
  <TextArea placeholder="This is a placeholder" />
</App>

readOnly (default: false)

Set this property to true to disallow changing the component value.

<App>
  <TextArea initialValue="Example text" readOnly="{true}" />
</App>

required

Set this property to true to indicate it must have a value before submitting the containing form.

resize

This optional property specifies in which dimensions can the TextArea be resized by the user.

Available values:

If you allow resizing, the TextArea turns off automatic sizing.

When you allow vertical resizing, you can limit the sizable range according to minRows and maxRows.

Drag the small resize indicators at the bottom right on each of the controls in the demo.

<App>
  <TextArea resize="vertical" minRows="1" maxRows="8" />
  <TextArea resize="both" />
</App>

rows (default: 2)

Specifies the number of rows the component initially has.

Note: If either autoSize, maxRows or minRows is set, the rows prop has no effect.

<App>
  <TextArea rows="10" />
</App>

validationStatus (default: "none")

This property allows you to set the validation status of the input component.

Available values:

This prop is used to visually indicate status changes reacting to form field validation.

<App>
  <TextArea />
  <TextArea validationStatus="valid" />
  <TextArea validationStatus="warning" />
  <TextArea validationStatus="error" />
</App>

Events

didChange

This event is triggered when value of TextArea has changed.

Write in the input field and see how the Text underneath it is updated in parallel.

<App var.field="">
  <TextArea autoFocus="true" initialValue="{field}" onDidChange="(val) => field = val" />
  <Text value="{field}" />
</App>

gotFocus

This event is triggered when the TextArea has received the focus.

Clicking on the TextArea in the example demo changes the label text. Note how clicking elsewhere resets the text to the original.

<App>
  <TextArea
    initialValue="{focused === true ? 'I got focused!' : 'I lost focus...'}"
    onGotFocus="focused = true"
    onLostFocus="focused = false"
    var.focused="{false}" />
</App>

lostFocus

This event is triggered when the TextArea has lost the focus.

Exposed Methods

focus

This method sets the focus on the TextArea.

<App>
  <Button label="Trigger Focus" onClick="inputComponent.focus()" />
  <TextArea id="inputComponent" />
</App>

setValue

You can use this method to set the component's current value programmatically (true: checked, false: unchecked).

<App var.changes="">
  <TextArea
    id="inputField"
    readOnly="true"
    onDidChange="changes++" />
  <HStack>
    <Button
      label="Check"
      onClick="inputField.setValue('example ')" />
    <Text value="Number of changes: {changes}" />
  </HStack>
</App>

value

You can query the component's value. If no value is set, it will retrieve undefined.

In the example below, typing in the TextArea will also display the length of the text typed into it above the field:

<App>
  <Text value="TextArea content length: {inputComponent.value.length}" />
  <TextArea id="inputComponent" />
</App>

Styling

The TextArea component uses these theme variables.

These variables have 4 variants depending on the validationStatus denoted by |status|. If the status segment is omitted, the style will be applied to all validation statuses.

• borderRadius-TextArea-|status|
• borderWidth-TextArea-|status|
• borderStyle-TextArea-|status|
• fontSize-TextArea-|status|
• color-placeholder-TextArea-|status|

"borderRadius-TextArea-default": "10px",
"color-placeholder-TextArea-error": "crimson"

In addition to the validation statuses, the variables below are associated with styles for hover and focus interaction states denoted by |interact| in their signature:

• borderColor-TextArea-|status|--|interact|
• backgroundColor-TextArea-|status|--|interact|
• boxShadow-TextArea-|status|--|interact|
• textColor-TextArea-|status|--|interact|

"backgroundColor-TextArea-default--hover": "gray",
"textColor-TextArea-error--focus": "lightcoral"

The following variables are only used in the focus state:

• outlineWidth-TextArea-|status|--focus
• outlineColor-TextArea-|status|--focus
• outlineStyle-TextArea-|status|--focus
• outlineOffset-TextArea-|status|--focus

These variables set the disabled state:

• backgroundColor-TextArea--disabled
• textColor-TextArea--disabled
• borderColor-TextArea--disabled

Example

"borderRadius-TextArea": "30px",
"color-placeholder-TextArea-default": "blue"

To style all input controls not just this component, replace the TextArea segment with Input:

borderColor-Input: "#0033FF"

Input affects the following controls:

• Checkbox
• NumberBox
• RadioGroupOption
• Select
• Switch
• TextBox
• MultiSelect
• MultiCombobox

See custom themes for styling details.