# Textarea Component

The Textarea component represents a multi-line plain-text editing control, useful when you want to allow users to enter a sizeable amount of free-form text, for example a comment on a review or feedback form.

# Usage:

- The <Textarea> component is often used in a form, to collect user inputs like comments or reviews.
- A text area can hold an unlimited number of characters, and the text renders

# Getting Started

#### Include the following code

1.  Include Textarea component
    i) UnControlled Component
    ```js
    import Textarea from '@zohodesk/unifiedcomponents/lib/components/textarea/Textarea';
    ```
    ii) Controlled Component
    ```js
    import { TextareaControlled } from '@zohodesk/unifiedcomponents/lib/components/textarea/Textarea';
    ```
2.  Include Textarea constant props
    ```js
    import textareaConstantProps from '@zohodesk/unifiedcomponents/lib/components/textarea/Textarea.constantProps';
    ```
3.  Render Textarea component
    ```js
    export default function App() {
      return (
        <ThemeProvider>
          <Textarea
            size={textareaConstantProps.size.medium}
            variant={textareaConstantProps.variant.outline}
            color={textareaConstantProps.color.danger}
          />
        </ThemeProvider>
      );
    }
    ```

---

### The Uncontrolled

**Uncontrolled Component** are like traditional Textarea form:

```js
import Textarea from '@zohodesk/unifiedcomponents/lib/components/textarea/Textarea';
<Textarea defaultValue={'textarea content'} onChange={handleChange} />;
```

They remember what you typed. You can then get their value. For example, in onClick handler of a button:

```js
function Form (){
    const [desc, setDesc] = useState('');
    function handleSubmitClick(){
        setDesc('defaultValue');
    }
    return (
      <div>
        <Textarea defaultValue={desc} onChange={(content, ev)=>{setDesc(content); />
        <button onClick={handleSubmitClick}>Submit</button>
      </div>
    );
}
```

In other words, **you have to 'pull' the value from the field when you need it.** This can happen when the form is submitted.

### The Controlled

A **controlled component** accepts its current value as a prop, as well as a callback to change that value. You could say it's a more "React way" of approaching this (which doesn't mean you should always use it).

```js
import TextareaControlled from '@zohodesk/unifiedcomponents/lib/components/textarea/Textarea';
<TextareaControlled value={'textarea content'} onChange={handleChange} />;
```

Which is fine and all... but the value of this input has to live in the state somewhere. Typically, the component that renders the form component saves that in its state.

```js
function Form() {
  const [desc, setDesc] = useState('');
  function handleDescChange(event) {
    setDesc(event.target.value);
  }
  return (
    <div>
      <TextareaControlled value={desc} onChange={handleDescChange} />
    </div>
  );
}
```

Every time you type a new character, handleNameChange is called. It takes in the new value of the input and sets it in the state.
**This flow kind of 'pushes' the value changes to the form component**, so the Form component always has the current value of the input, without needing to ask for it explicitly.

### Textarea PropTypes

| Prop name       | Type                                                                    | Default         | Required | Description                                                                                                                                                                                                                                                |
| --------------- | ----------------------------------------------------------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- | ------------- |
| id              | **string**                                                              | -               | -        | An **id** attribute to allow the <Textarea> component for accessibility purposes.                                                                                                                                                                          |
| name            | **string**                                                              | -               | -        | The name of the control.                                                                                                                                                                                                                                   |
| placeholder     | **string**                                                              | -               | -        | A hint to the user of what can be entered in the control. Carriage returns or line-feeds within the placeholder text must be treated as line breaks when rendering the hint.                                                                               |
| value           | **string**                                                              | -               | -        | Specifies the text area input value.                                                                                                                                                                                                                       |
| defaultValue    | **string**                                                              | -               | -        | Use state value in uncontrolled textarea component.                                                                                                                                                                                                        |
| required        | **boolean**                                                             | **false**       | -        | Specifies that a text area is required/must be filled out. If true, the textarea control will be required. This has 2 side effects: - The Textarea will show a required indicator - The form element (e.g, Input) will have **aria-required** set to true. |
| readOnly        | **boolean**                                                             | **false**       | -        | Specifies that a text area should be read-only. If true, the text area control will be readonly.                                                                                                                                                           |
| rows            | **number**                                                              | -               | -        | The number of visible text lines for the control.                                                                                                                                                                                                          |
| cols            | **number**                                                              | -               | -        | The visible width of the text control, in average character widths. If it is specified, it must be a positive integer.                                                                                                                                     |
| resize          | **["resize_none","resize_horizontal","resize_vertical","resize_both"]** | **resize_both** | -        | Specifies the resize both the height and width of the element.                                                                                                                                                                                             |
| autoFocus       | **boolean**                                                             | **false**       | -        | Specifies that a text area should automatically get focus when the page loads.                                                                                                                                                                             |
| disabled        | **boolean**                                                             | **false**       | -        | Specifies the text area should be disabled. If true, the form control will be disabled.                                                                                                                                                                    |
| minLength       | **number**                                                              | -               | -        | The minimum number of characters (UTF-16 code units) required that the user should enter.                                                                                                                                                                  |
| maxLength       | **number**                                                              | -               | -        | The maximum number of characters (UTF-16 code units) that the user can enter. If this value isn't specified, the user can enter an unlimited number of characters.                                                                                         |
| variant         | **["outline", "flushed", "filled", "plain"]**                           | -               | -        | Specifies the variant type of text area like ["outline"                                                                                                                                                                                                    | "flushed" | "filled" | "unstyled" ]. |
| animateOnFocus  | **number**                                                              | **false**       | -        | Specifies the visible text height increased in focused time. if true the text height increased.                                                                                                                                                            |
| color           | **["default", "primary", "danger"]**                                    | -               | -        | Specifies the variant color of text area like ["default","primary", "danger"].                                                                                                                                                                             |
| size            | **["size_sm","size_md","size_lg"]**                                     | -               | -        | Specifies the visible text height like [small, medium, Large].                                                                                                                                                                                             |
| onBlur          | **function**                                                            | -               | -        | Event occurs when an object loses focus.                                                                                                                                                                                                                   |
| onChange        | **function**                                                            | -               | -        | Event occurs when the value of an element has been changed.                                                                                                                                                                                                |
| onClick         | **function**                                                            | -               | -        | Event occurs when the user clicks on an element.                                                                                                                                                                                                           |
| onFocus         | **function**                                                            | -               | -        | Event occurs when an element gets focus.                                                                                                                                                                                                                   |
| onKeyDown       | **function**                                                            | -               | -        | Event occurs when the user is pressing a key (on the keyboard).                                                                                                                                                                                            |
| onKeyUp         | **function**                                                            | -               | -        | Event occurs when the user releases a key (on the keyboard).                                                                                                                                                                                               |
| onkeypress      | **function**                                                            | -               | -        | Event occurs when the user presses a key (on the keyboard).                                                                                                                                                                                                |
| role            | **string**                                                              | -               | -        | The role is used to communicate an important and usually time-sensitive message to the user.                                                                                                                                                               |
| tabIndex        | **string, number**                                                      | -               | -        | Specifies the keyboard tab order of the textarea relative to the other controls on the page.The tabIndex value indicates when the textarea can be focused.                                                                                                 |
| ariaLabel       | **string**                                                              | -               | -        | Defines a string value that labels an interactive element                                                                                                                                                                                                  |
| ariaLabelledby  | **string**                                                              | -               | -        | Enables authors to reference other elements on the page to define an accessible name.                                                                                                                                                                      |
| ariaPlaceholder | **string**                                                              | -               | -        | Represents a hint (word or phrase) to the user about what to enter into the text field                                                                                                                                                                     |
| ariaRequired    | **boolean**                                                             | -               | -        | Indicates that a value must be provided for the field before it is submitted.                                                                                                                                                                              |
| ariaReadonly    | **boolean**                                                             | -               | -        | Indicates that the user cannot modify the value of the text field.                                                                                                                                                                                         |
| ariaDisabled    | **boolean**                                                             | -               | -        | Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.                                                                                                                                                       |

---

##### Reference

1. [Textarea Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)
2. [Textarea tag](https://www.w3schools.com/tags/tag_textarea.asp)
3. [ARIA states and properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes)
4. [Controlled vs UnControlled](https://goshacmd.com/controlled-vs-uncontrolled-inputs-react/)
