Reference

<textarea>

To display a text area, render the component.

Props

<textarea> supports all

You can by passing a value prop:

  • value: A string. Controls the text inside the text area.

When you pass value, you must also pass an onChange handler that updates the passed value.

If your <textarea> is uncontrolled, you may pass the defaultValue prop instead:

  • defaultValue: A string. Specifies for a text area.

These <textarea> props are relevant both for uncontrolled and controlled text areas:

  • : Either 'on' or 'off'. Specifies the autocomplete behavior.
  • : A boolean. If true, React will focus the element on mount.
  • children: <textarea> does not accept children. To set the initial value, use defaultValue.
  • : A number. Specifies the default width in average character widths. Defaults to 20.
  • : A boolean. If true, the input will not be interactive and will appear dimmed.
  • : A string. Specifies the id of the <form> this input belongs to. If omitted, it’s the closest parent form.
  • : A number. Specifies the maximum length of text.
  • : A number. Specifies the minimum length of text.
  • : A string. Specifies the name for this input that’s
  • onChange: An function. Required for Fires immediately when the input’s value is changed by the user (for example, it fires on every keystroke). Behaves like the browser
  • onChangeCapture: A version of onChange that fires in the
  • : An function. Fires immediately when the value is changed by the user. For historical reasons, in React it is idiomatic to use onChange instead which works similarly.
  • onInputCapture: A version of onInput that fires in the
  • : An function. Fires if an input fails validation on form submit. Unlike the built-in invalid event, the React onInvalid event bubbles.
  • onInvalidCapture: A version of onInvalid that fires in the
  • : An function. Fires after the selection inside the <textarea> changes. React extends the onSelect event to also fire for empty selection and on edits (which may affect the selection).
  • onSelectCapture: A version of onSelect that fires in the
  • : A string. Displayed in a dimmed color when the text area value is empty.
  • : A boolean. If true, the text area is not editable by the user.
  • : A boolean. If true, the value must be provided for the form to submit.
  • : A number. Specifies the default height in average character heights. Defaults to 2.
  • : Either 'hard', 'soft', or 'off'. Specifies how the text should be wrapped when submitting a form.

Caveats

  • Passing children like <textarea>something</textarea> is not allowed.
  • If a text area receives a string value prop, it will be
  • A text area can’t be both controlled and uncontrolled at the same time.
  • A text area cannot switch between being controlled or uncontrolled over its lifetime.
  • Every controlled text area needs an onChange event handler that synchronously updates its backing value.

Usage

Displaying a text area

Render <textarea> to display a text area. You can specify its default size with the and attributes, but by default the user will be able to resize it. To disable resizing, you can specify resize: none in the CSS.

Providing a label for a text area

Typically, you will place every <textarea> inside a tag. This tells the browser that this label is associated with that text area. When the user clicks the label, the browser will focus the text area. It’s also essential for accessibility: a screen reader will announce the label caption when the user focuses the text area.

If you can’t nest <textarea> into a <label>, associate them by passing the same ID to <textarea id> and To avoid conflicts between instances of one component, generate such an ID with

Providing an initial value for a text area

You can optionally specify the initial value for the text area. Pass it as the defaultValue string.

Reading the text area value when submitting a form

Add a around your textarea with a inside. It will call your <form onSubmit> event handler. By default, the browser will send the form data to the current URL and refresh the page. You can override that behavior by calling e.preventDefault(). Read the form data with .

Controlling a text area with a state variable

A text area like <textarea /> is uncontrolled. Even if you like <textarea defaultValue="Initial text" />, your JSX only specifies the initial value, not the value right now.

To render a controlled text area, pass the value prop to it. React will force the text area to always have the value you passed. Typically, you will control a text area by declaring a

This is useful if you want to re-render some part of the UI in response to every keystroke.

Troubleshooting

My text area doesn’t update when I type into it

If you render a text area with value but no onChange, you will see an error in the console:

Console
You provided a value prop to a form field without an onChange handler. This will render a read-only field. If the field should be mutable use defaultValue. Otherwise, set either onChange or readOnly.

As the error message suggests, if you only wanted to pass defaultValue instead:

If you want specify an onChange handler:

If the value is intentionally read-only, add a readOnly prop to suppress the error:

My text area caret jumps to the beginning on every keystroke

If you you must update its state variable to the text area’s value from the DOM during onChange.

You can’t update it to something other than e.target.value:

You also can’t update it asynchronously:

To fix your code, update it synchronously to e.target.value:

If this doesn’t fix the problem, it’s possible that the text area gets removed and re-added from the DOM on every keystroke. This can happen if you’re accidentally on every re-render. For example, this can happen if the text area or one of its parents always receives a different key attribute, or if you nest component definitions (which is not allowed in React and causes the “inner” component to remount on every render).

I’m getting an error: “A component is changing an uncontrolled input to be controlled”

If you provide a value to the component, it must remain a string throughout its lifetime.

You cannot pass value={undefined} first and later pass value="some string" because React won’t know whether you want the component to be uncontrolled or controlled. A controlled component should always receive a string value, not null or undefined.

If your value is coming from an API or a state variable, it might be initialized to null or undefined. In that case, either set it to an empty string ('') initially, or pass value={someValue ?? ''} to ensure value is a string.