# Textarea
> Textarea lets the user input plain-text on multiple lines.

## Import

```js
import { Textarea } from '@gemini-suite/vera-react';
```

## Examples

### Basic

```jsx
<Textarea aria-label="Textarea label" placeholder="Sample placeholder" />
```

### Controlled

It is most common to set up `Textarea` as a [controlled component](https://reactjs.org/docs/forms.html#controlled-components), meaning that React state drives its value. To achieve this you must provide `value` and `onChange` properties.

```jsx
() => {
  const [value, setValue] = React.useState('');
  const handleChange = event => setValue(event.target.value);

  return (
    <Flex flow="column" gap="spacingS">
      <Box>Value: {value}</Box>
      <Textarea
        value={value}
        onChange={handleChange}
        aria-label="Textarea label"
        placeholder="Enter value"
      />
    </Flex>
  );
};
```

### With Form Field

`Textarea` should be clearly labeled so it's obvious to users what they should enter. Optionally, you may want to connect helper text and/or validation feedback message to the `textarea` element.
Thus it is recommended to wrap textareas with [Form Field](/components/forms/form-field) to create a consistent set of form fields that are accessible to screen reader users.

```jsx
<Flex flow="column" gap="spacingM">
  <FormField.Root as={Flex} flow="column">
    <FormField.Label>{'Message'}</FormField.Label>
    <FormField.HelperText>
      {'Help or instruction text goes here.'}
    </FormField.HelperText>
    <Textarea placeholder="Leave something here…" />
  </FormField.Root>
  <FormField.Root as={Flex} flow="column" validationStatus="error" isRequired>
    <FormField.Label>{'Message'}</FormField.Label>
    <Textarea placeholder="Leave something here…" />
    <FormField.FeedbackMessage>
      <FormField.FeedbackIcon />
      {'Message is required.'}
    </FormField.FeedbackMessage>
  </FormField.Root>
</Flex>
```

### Placeholder

Placeholder text provides examples of the type of data a user should enter.

<Callout variant="important">

Placeholder text disappears after the user begins entering data into the textarea and should not contain crucial information. Do not use placeholder text as a replacement for labels or descriptions.

</Callout>

```jsx
<FormField.Root as={Flex} flow="column">
  <FormField.Label>{'Tell us about yourself'}</FormField.Label>
  <Textarea placeholder="e.g. your hobbies and interests" />
</FormField.Root>
```

### Disabled textarea

Pass `isDisabled` prop to the accompanying `FormField` and it will cascade down to the textarea.

```jsx
<FormField.Root as={Flex} flow="column" isDisabled>
  <FormField.Label>{'Message'}</FormField.Label>
  <Textarea />
</FormField.Root>
```

You can also pass `isDisabled` prop directly to `Textarea`.

```jsx
<Textarea aria-label="Input label" isDisabled />
```

### Sizes

Vera provides two `Textarea` sizes ‐ `medium` and `small`, with the `medium` size used by default. All sizes are aligned with sizes of other related components like [Text Input](/components/forms/text-input) or [Select](/components/forms/select).

```jsx
<Flex flow="column">
  <Textarea size="small" placeholder="Message…" />
  <Textarea size="medium" placeholder="Message…" />
</Flex>
```

#### Size inheritance

`Textarea` automatically inherits size, when placed inside a [FormField component](/components/forms/form-field).

```jsx
<Flex flow="column">
  <FormField.Root as={Flex} flow="column" size="small">
    <FormField.Label>{'Small'}</FormField.Label>
    <Textarea placeholder="Message…" />
  </FormField.Root>
  <FormField.Root as={Flex} flow="column">
    <FormField.Label>{'Medium'}</FormField.Label>
    <Textarea placeholder="Message…" />
  </FormField.Root>
</Flex>
```

#### Responsive

`Textarea` supports responsive syntax for its `size` property, which means you can change its size based on the viewport.

```jsx
<Textarea
  aria-label="Enter message"
  size={{ '@initial': 'medium', '@mqLargeAndUp': 'small' }}
  placeholder="Message…"
/>
```

#### Multi-sizing

Vera provides `applySizes` utility, which lets you specify size "scopes" within your app.
All textareas within a scope will share the same size unless overwritten on a per-control basis.

```jsx
<Flex
  gap="spacingS"
  className={applySizes({
    control: 'small'
  })}
  flow="column"
>
  <Textarea aria-label="Enter message" placeholder="Message…" />
  <Textarea aria-label="Enter message" placeholder="Message…" />
</Flex>
```

### Automatic rows adjustment

Automatic rows adjustment can be accomplished using the `autoResize` prop.

```jsx
<FormField.Root as={Flex} flow="column">
  <FormField.Label>{'Textarea that resizes automatically'}</FormField.Label>
  <Textarea autoResize />
</FormField.Root>
```

---

## API Reference

<Callout variant="tip">

In addition to the props below, you can pass all `React.TextareaHTMLAttributes`.

</Callout>

| Name               | Type                                | Default | Description                                                                                                                                                                                                                                  | Required |
| ------------------ | ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`              | `StitchesCss`                       |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |
| `isDisabled`       | `boolean`                           |         | When `true`, the textarea will be disabled, preventing the user from interacting with it.                                                                                                                                                    |          |
| `isReadOnly`       | `boolean`                           |         | When `true`, the textarea will be readonly, which means its value cannot be edited but it can still be selected and copied.                                                                                                                  |          |
| `isRequired`       | `boolean`                           |         | When `true`, the textarea will be required.                                                                                                                                                                                                  |          |
| `validationStatus` | `"error" \| "success" \| "warning"` |         | Styles the textarea to match the status.                                                                                                                                                                                                     |          |
| `size`             | `"medium" \| "small"`               |         | The size of the textarea.                                                                                                                                                                                                                    |          |
| `autoResize`       | `boolean`                           | `false` | When `true`, size of the textarea will adjust automatically.                                                                                                                                                                                 |          |