@primer/react-brand/docs/forms/TextArea/index.md

Primer Brand is a GitHub's design system for creating React-based marketing websites and digital experiences.

---
title: Textarea
description: Use the textarea component for multi-line text input form fields.
keywords: ['input', 'form']
source: https://github.com/primer/brand/blob/main/packages/react/src/forms/Textarea/Textarea.tsx
storybook: '/brand/storybook/?path=/story/components-forms-textarea--default'
---

```js
import {Textarea} from '@primer/react-brand'
```

## Examples

> Textarea components **must always** be accompanied by a corresponding label to improve support for assistive
> technologies. Examples below are provided for conciseness and may not reflect accessibility best practices.
>
> Use the [FormControl](../FormControl/index.md) component to render a Textarea with a corresponding label.

### Controlled mode

```jsx filename="noinline"
const TextareaExample = () => {
  // Running in controlled mode (recommended)
  const [value, setValue] = React.useState('This value was initially set through state.')

  const handleChange = event => {
    setValue(event.target.value)
  }

  return <Textarea aria-label="Description" placeholder="Enter a description" onChange={handleChange} value={value} />
}

render(<TextareaExample />)
```

### Uncontrolled mode

```jsx filename="noinline"
const TextareaExample = () => {
  const ref = React.useRef()

  const handleSubmit = event => {
    event.preventDefault()
    if (!ref.current.value) {
      alert(`Enter a value into the Textarea and press submit`)
      return
    }

    alert(`Current Textarea value: ${ref.current.value}`)
  }

  return (
    <form onSubmit={handleSubmit}>
      <Textarea
        cols={40}
        rows={8}
        ref={ref}
        defaultValue="Set the initial state in uncontrolled mode using the defaultValue prop"
        aria-label="Demo Textarea"
      />
      <br /> <br />
      <Button variant="primary" type="submit">
        Submit
      </Button>
    </form>
  )
}

render(<TextareaExample />)
```

### Displaying form validation state

```jsx
<Stack direction={{narrow: 'vertical', wide: 'horizontal'}}>
  <Stack direction="vertical">
    <FormControl validationStatus="success">
      <FormControl.Label>Success state</FormControl.Label>
      <Textarea />
      <FormControl.Validation>This is a success message</FormControl.Validation>
    </FormControl>
  </Stack>
  <Stack direction="vertical">
    <FormControl validationStatus="error">
      <FormControl.Label>Error state</FormControl.Label>
      <Textarea />
      <FormControl.Validation>This is an error message</FormControl.Validation>
    </FormControl>
  </Stack>
</Stack>
```

### Inactive

```jsx
<Textarea disabled aria-label="Demo Textarea">
  This text is inactive
</Textarea>
```

### Resize

By default, `Textarea` can be resized by the user vertically and horizontally. Resizing can be prevented by setting `resize` to `none`

```jsx
<Textarea resize="none" aria-label="Resizable Textarea" />
```

## Props

### Textarea

| Name               | Type                                             |  Default | Description                                                                        |
| :----------------- | :----------------------------------------------- | :------: | :--------------------------------------------------------------------------------- |
| `className`        | `string`                                         |          | Sets a custom class                                                                |
| `cols`             | `number`                                         |   `30`   | Specifies the visible width of a textarea.                                         |
| `id`               | `string`                                         |          | Sets a custom id                                                                   |
| `ref`              | `React.RefObject`                                |          | Forward a Ref to the underlying DOM node                                           |
| `required`         | `boolean`                                        |          | Indicates to the user and assistive technologies that the field value is required. |
| `resize`           | `'both' \| 'horizontal' \| 'vertical' \| 'none'` | `'both'` | Sets whether an element is resizable, and if so, in which directions.              |
| `rows`             | `number`                                         |    `7`   | Specifies the visible height of a text area.                                       |
| `size`             | `'medium' \| 'large'`                            |          | Provides alternate visual presentation.                                            |
| `validationStatus` | `'error' \| 'success'`                           |          | Applies visual and semantic state to the underlying elements                       |

Additional props can be passed to the `<textarea>` element. [See MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea) accepted by the `<textarea>` element.