index.mdx

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

import {TextAreaSizeProp, TextAreaValidationStatusProp, TextAreaResizeProp} from './react'

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 component to render a Textarea with a corresponding label.

Controlled mode

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

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

<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

<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

<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'	Sets whether an element is resizable, and if so, in which directions.
rows	number	7	Specifies the visible height of a text area.
size			Provides alternate visual presentation.
validationStatus			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 accepted by the <textarea> element.