TextArea

TextArea provides a multiline text input area.

It is often used in forms, see this guide for details.

Behaviors

This component supports the following behaviors:

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>

<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>

<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>

<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>

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

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. If not set, the number of rows is unlimited.

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>

<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. If not set, the minimum number of rows is 1.

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>

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

placeholder

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

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

<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>

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

required

default: false

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>

<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>

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

validationIconError

Icon to display for error state when concise validation summary is enabled.

validationIconSuccess

Icon to display for valid state when concise validation summary is enabled.

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>

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

verboseValidationFeedback

Enables a concise validation summary (icon) in input components.

Events

didChange

This event is triggered when value of TextArea has changed.

Signature: didChange(newValue: any): void

• newValue: The new value of the component.

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

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

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

gotFocus

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

Signature: gotFocus(): void

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>

<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.

Signature: lostFocus(): void

Exposed Methods

focus

This method sets the focus on the TextArea component.

Signature: focus(): void

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

<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>

<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.

Signature: get value(): string | 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>

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

Parts

The component has some parts that can be styled through layout properties and theme variables separately:

• endAdornment: The adornment displayed at the end of the text area.
• input: The text area input.
• label: The label displayed for the text area.
• startAdornment: The adornment displayed at the start of the text area.

Styling

Theme Variables