Text Area

Input field for entering more than one line of text.

UsageGuidelinesAPI

A TextArea is an input field that allows the user to enter more than one line of text.

Note: the HTML element is called "textarea", one word — but the React component is "TextArea", as if it were two words.

Usage

ReactVanilla

<TextArea placeholder="Enter your text" />

<TextArea placeholder="Enter your text" />

<textarea placeholder="Enter your text" class="swan-textarea"></textarea>

<textarea placeholder="Enter your text" class="swan-textarea"></textarea>

Our Textarea component uses the native HTML <textarea> input, so it can use the various properties of the native element, including the rows property to control the textarea's default height.

Resizing

By default, users can resize the Textarea both vertically and horizontally. If you want to limit resizing to the vertical axis, you can add the "resize vertical" option:

ReactVanilla

<TextArea placeholder="Enter your text" resize="vertical" />

<TextArea placeholder="Enter your text" resize="vertical" />

<textarea
  placeholder="Enter your text"
  class="swan-textarea swan-textarea-resize-vertical"
></textarea>

<textarea
  placeholder="Enter your text"
  class="swan-textarea swan-textarea-resize-vertical"
></textarea>

This pairs well with the "full width" option, which makes the component take up all available width:

ReactVanilla

<TextArea placeholder="Enter your text" rows={4} fullWidth resize="vertical" />

<TextArea placeholder="Enter your text" rows={4} fullWidth resize="vertical" />

<textarea
  rows="4"
  placeholder="Enter your text"
  class="swan-textarea swan-textarea-full-width swan-textarea-resize-vertical"
></textarea>

<textarea
  rows="4"
  placeholder="Enter your text"
  class="swan-textarea swan-textarea-full-width swan-textarea-resize-vertical"
></textarea>

Labels, Errors, and Helper Text

Use skin="error" for when the current value is invalid:

ReactVanilla

<TextArea placeholder="Enter your text" skin="error" />

<TextArea placeholder="Enter your text" skin="error" />

<textarea
  placeholder="Enter your text"
  class="swan-textarea swan-textarea-skin-error"
></textarea>

<textarea
  placeholder="Enter your text"
  class="swan-textarea swan-textarea-skin-error"
></textarea>

In React, when you use a TextArea inside a FormField along with other components, the "error" skin will be automatically applied when a FormError component is present. You'll get some other convenience behaviors, including the textarea's label automatically having its for attribute associated with the input. Refer to Form for more.

In vanilla, you can get the error skin by applying the class swan-textarea-skin-error to the input.

Managing State

As is the case with most form elements, folks often want to "control" this component. Controlling a component means that you take ownership over its state rather than letting the browser manage the state for you. When you control component, you own the source of truth for the UI. This means that you don't need to query the DOM in order to determine the current value of the element. So, when it comes time to use the value of the element somewhere else (e.g. submitting the value to a back-end service) you can trust your stored state.

If you'd like to control a TextArea, you'll need store the current value somewhere (e.g. React state or a Redux store), and you'll need to provide a handler to update that value when the user interacts with the component.

e.g.

() => {
  const [value, setValue] = React.useState('')
  return (
    <TextArea
      placeholder="Enter your text"
      value={value}
      onChange={event => setValue(event.target.value)}
    />
  )
}

() => {
  const [value, setValue] = React.useState('')
  return (
    <TextArea
      placeholder="Enter your text"
      value={value}
      onChange={event => setValue(event.target.value)}
    />
  )
}

If you don't care about the state of the TextArea, you can simply omit the value and onChange props. In this case, you may add the defaultValue prop in order to specify the initial value of the TextArea without committing to fully managing the state.

We don't have any guidelines for Text Area yet but reach out to us with the questions you'd like answered or if you'd like to contribute any guidelines.

Props

TextArea

This component is implemented using the <textarea /> as the root element. You can utilize the native attributes supported by <textarea /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
skin	`"standard" \| "error" \| null`	false	The visual variant. Note that error is implied if the TextInput is used inside of a FormInput that also contains a FormError. Available options: 'standard', 'error'	null
resize	`"both" \| "vertical" \| null`	false	Which dimensions of the TextArea should be resizable. Available options: 'vertical', 'both'	null
fullWidth	`boolean \| null`	false	Whether or not the TextArea should expand to fill the full width of its container	null

Was this page useful?

form

Published: Jan 30, 2022Last updated: Sep 3, 2024

Text Area

Usage

Resizing

Labels, Errors, and Helper Text

Managing State

Props

Related