TextArea

TextArea provides a multiline text input area.

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

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>

Example: autoSize

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

Example: enabled

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

Example: enterSubmits

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

Example: initialValue

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

`label`

This property sets the label of the component. If not set, the component will not display a label.

`labelBreak` (default: true)

This boolean value indicates whether the TextArea label 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:

Value	Description
`start`	The left side of the input (left-to-right) or the right side of the input (right-to-left)
`end`	The right side of the input (left-to-right) or the left side of the input (right-to-left)
`top`	The top of the input (default)
`bottom`	The bottom of the input

`labelWidth`

This property sets the width of the TextArea component's label. If not defined, the label's width will be determined by its content and the available space.

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

Example: maxRows

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

Example: minRows

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

Example: placeholder

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

Example: readOnly

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

Value	Description
`(undefined)`	No resizing
`horizontal`	Can only resize horizontally
`vertical`	Can only resize vertically
`both`	Can resize in both dimensions

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>

Example: resize

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

Example: rows

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

`validationStatus` (default: "none")

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

Available values:

Value	Description
`valid`	Visual indicator for an input that is accepted
`warning`	Visual indicator for an input that produced a warning
`error`	Visual indicator for an input that produced an error

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>

Example: validationStatus

<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 
    initialValue="{field}" 
    onDidChange="(val) => field = val" 
  />
  <Text value="{field}" />
</App>

Example: didChange

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

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>

Example: gotFocus/lostFocus

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

Signature: focus(): void

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

Example: focus

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

Example: setValue

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

Example: value

<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

Variable	Default Value (Light)	Default Value (Dark)
backgroundColor-TextArea--disabled	none	none
backgroundColor-TextArea-default	none	none
backgroundColor-TextArea-default--focus	none	none
backgroundColor-TextArea-default--hover	none	none
backgroundColor-TextArea-error	none	none
backgroundColor-TextArea-error--focus	none	none
backgroundColor-TextArea-error--hover	none	none
backgroundColor-TextArea-success	none	none
backgroundColor-TextArea-success--focus	none	none
backgroundColor-TextArea-success--hover	none	none
backgroundColor-TextArea-warning	none	none
backgroundColor-TextArea-warning--focus	none	none
backgroundColor-TextArea-warning--hover	none	none
borderColor-TextArea--disabled	none	none
borderColor-TextArea-default	none	none
borderColor-TextArea-default--focus	none	none
borderColor-TextArea-default--hover	none	none
borderColor-TextArea-error	none	none
borderColor-TextArea-error--focus	none	none
borderColor-TextArea-error--hover	none	none
borderColor-TextArea-success	none	none
borderColor-TextArea-success--focus	none	none
borderColor-TextArea-success--hover	none	none
borderColor-TextArea-warning	none	none
borderColor-TextArea-warning--focus	none	none
borderColor-TextArea-warning--hover	none	none
borderRadius-TextArea-default	none	none
borderRadius-TextArea-error	none	none
borderRadius-TextArea-success	none	none
borderRadius-TextArea-warning	none	none
borderStyle-TextArea-default	none	none
borderStyle-TextArea-error	none	none
borderStyle-TextArea-success	none	none
borderStyle-TextArea-warning	none	none
borderWidth-TextArea-default	none	none
borderWidth-TextArea-error	none	none
borderWidth-TextArea-success	none	none
borderWidth-TextArea-warning	none	none
boxShadow-TextArea-default	none	none
boxShadow-TextArea-default--focus	none	none
boxShadow-TextArea-default--hover	none	none
boxShadow-TextArea-error	none	none
boxShadow-TextArea-error--focus	none	none
boxShadow-TextArea-error--hover	none	none
boxShadow-TextArea-success	none	none
boxShadow-TextArea-success--focus	none	none
boxShadow-TextArea-success--hover	none	none
boxShadow-TextArea-warning	none	none
boxShadow-TextArea-warning--focus	none	none
boxShadow-TextArea-warning--hover	none	none
fontSize-placeholder-TextArea-default	none	none
fontSize-placeholder-TextArea-error	none	none
fontSize-placeholder-TextArea-success	none	none
fontSize-placeholder-TextArea-warning	none	none
fontSize-TextArea-default	none	none
fontSize-TextArea-error	none	none
fontSize-TextArea-success	none	none
fontSize-TextArea-warning	none	none
outlineColor-TextArea-default--focus	none	none
outlineColor-TextArea-error--focus	none	none
outlineColor-TextArea-success--focus	none	none
outlineColor-TextArea-warning--focus	none	none
outlineOffset-TextArea-default--focus	none	none
outlineOffset-TextArea-error--focus	none	none
outlineOffset-TextArea-success--focus	none	none
outlineOffset-TextArea-warning--focus	none	none
outlineStyle-TextArea-default--focus	none	none
outlineStyle-TextArea-error--focus	none	none
outlineStyle-TextArea-success--focus	none	none
outlineStyle-TextArea-warning--focus	none	none
outlineWidth-TextArea-default--focus	none	none
outlineWidth-TextArea-error--focus	none	none
outlineWidth-TextArea-success--focus	none	none
outlineWidth-TextArea-warning--focus	none	none
padding-TextArea	none	none
paddingBottom-TextArea	none	none
paddingHorizontal-TextArea	$space-2	$space-2
paddingLeft-TextArea	none	none
paddingRight-TextArea	none	none
paddingTop-TextArea	none	none
paddingVertical-TextArea	$space-2	$space-2
textColor-placeholder-TextArea-default	none	none
textColor-placeholder-TextArea-error	none	none
textColor-placeholder-TextArea-success	none	none
textColor-placeholder-TextArea-warning	none	none
textColor-TextArea--disabled	none	none
textColor-TextArea-default	none	none
textColor-TextArea-default--focus	none	none
textColor-TextArea-default--hover	none	none
textColor-TextArea-error	none	none
textColor-TextArea-error--focus	none	none
textColor-TextArea-error--hover	none	none
textColor-TextArea-success	none	none
textColor-TextArea-success--focus	none	none
textColor-TextArea-success--hover	none	none
textColor-TextArea-warning	none	none
textColor-TextArea-warning--focus	none	none
textColor-TextArea-warning--hover	none	none

TextArea

Properties

autoFocus (default: false)

autoSize (default: false)

enabled (default: true)

enterSubmits (default: true)

escResets (default: false)

initialValue

label

labelBreak (default: true)

labelPosition (default: "top")

labelWidth

maxLength

maxRows

minRows

placeholder

readOnly (default: false)

required (default: false)

resize

rows (default: 2)

validationStatus (default: "none")

Events

didChange

gotFocus

lostFocus

Exposed Methods

focus

setValue

value

Parts

Styling

Theme Variables

`autoFocus` (default: false)

`autoSize` (default: false)

`enabled` (default: true)

`enterSubmits` (default: true)

`escResets` (default: false)

`initialValue`

`label`

`labelBreak` (default: true)

`labelPosition` (default: "top")

`labelWidth`

`maxLength`

`maxRows`

`minRows`

`placeholder`

`readOnly` (default: false)

`required` (default: false)

`resize`

`rows` (default: 2)

`validationStatus` (default: "none")

`didChange`

`gotFocus`

`lostFocus`

`focus`

`setValue`

`value`