Textarea
Textarea component is a multi-line Input which allows you to write large texts.
Installation
npx nextui-cli@latest add input
The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.
Import
Usage
Disabled
Read Only
Required
If you pass the isRequired property to the input, it will have a danger asterisk at
the end of the label and the textarea will be required.
Autosize
Textarea grows automatically based on the content, but you can also set a min and max height to
it using the minRows and maxRows properties. It is based on react-textarea-autosize.
Without Autosize
In case you want to disable the autosize feature, you can use the disableAutosize property.
Variants
With Error Message
You can combine the isInvalid and errorMessage properties to show an invalid textarea.
Description
Controlled
You can use the value and onValueChange properties to control the input value.
Clear Button
If you pass the isClearable property to the textarea, it will have a clear button at the
end of the textarea, it will be visible when the textarea has a value.
Note: NextUI
Textareaalso supports native events likeonChange, useful for form libraries such as Formik and React Hook Form.
Slots
- base: Input wrapper, it handles alignment, placement, and general appearance.
- label: Label of the textarea, it is the one that is displayed above, inside or left of the textarea.
- inputWrapper: Wraps the
label(when it is inside) and theinnerWrapper. - input: The textarea input element.
- description: The description of the textarea.
- errorMessage: The error message of the textarea.
- headerWrapper: Wraps the
labeland theclearButton.
Data Attributes
Textarea has the following attributes on the base element:
- data-invalid:
When the textarea is invalid. Based on
isInvalidprop. - data-required:
When the textarea is required. Based on
isRequiredprop. - data-readonly:
When the textarea is readonly. Based on
isReadOnlyprop. - data-hover: When the textarea is being hovered. Based on useHover
- data-focus: When the textarea is being focused. Based on useFocusRing.
- data-focus-visible: When the textarea is being focused with the keyboard. Based on useFocusRing.
- data-disabled:
When the textarea is disabled. Based on
isDisabledprop.
Accessibility
- Built with a native
<input>element. - Visual and ARIA labeling support.
- Change, clipboard, composition, selection, and input event support.
- Required and invalid states exposed to assistive technology via ARIA.
- Support for description and error message help text linked to the input via ARIA.
API
Textarea Props
| Attribute | Type | Description | Default |
|---|---|---|---|
| children | ReactNode | The content of the textarea. | - |
| minRows | number | The minimum number of rows to display. | 3 |
| maxRows | number | Maximum number of rows up to which the textarea can grow. | 8 |
| cacheMeasurements | boolean | Reuse previously computed measurements when computing height of textarea. | false |
| variant | flat | bordered | faded | underlined | The variant of the textarea. | flat |
| color | default | primary | secondary | success | warning | danger | The color of the textarea. | default |
| size | sm|md|lg | The size of the textarea. | md |
| radius | none | sm | md | lg | full | The radius of the textarea. | - |
| label | ReactNode | The content to display as the label. | - |
| value | string | The current value of the textarea (controlled). | - |
| defaultValue | string | The default value of the textarea (uncontrolled). | - |
| placeholder | string | The placeholder of the textarea. | - |
| startContent | ReactNode | Element to be rendered in the left side of the input. | - |
| endContent | ReactNode | Element to be rendered in the right side of the input. | - |
| description | ReactNode | A description for the textarea. Provides a hint such as specific requirements for what to choose. | - |
| errorMessage | ReactNode | ((v: ValidationResult) => ReactNode) | An error message for the textarea. | - |
| validate | (value: string) => ValidationError ｜ true ｜ null ｜ undefined | Validate input values when committing (e.g. on blur), returning error messages for invalid values. Validation errors are displayed upon form submission if validationBehavior is set to native. For real-time validation, use the isInvalid prop. | - |
| validationBehavior | native | aria | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. | aria |
| labelPlacement | inside | outside | outside-left | The position of the label. | inside |
| fullWidth | boolean | Whether the textarea should take up the width of its parent. | true |
| isRequired | boolean | Whether user input is required on the textarea before form submission. | false |
| isReadOnly | boolean | Whether the textarea can be selected but not changed by the user. | |
| isDisabled | boolean | Whether the textarea is disabled. | false |
| isClearable | boolean | Whether the textarea should have a clear button. | false |
| isInvalid | boolean | Whether the textarea is invalid. | false |
| validationState | valid | invalid | Whether the textarea should display its "valid" or "invalid" visual styling. (Deprecated) use isInvalid instead. | - |
| disableAutosize | boolean | Whether the textarea auto vertically resize should be disabled. | false |
| disableAnimation | boolean | Whether the textarea should be animated. | false |
| classNames | Record<"base"｜ "label"｜ "inputWrapper"｜ "innerWrapper" ｜ "input" ｜ "description" ｜ "errorMessage", string> | Allows to set custom class names for the checkbox slots. | - |
Input Events
| Attribute | Type | Description |
|---|---|---|
| onChange | React.ChangeEvent <HTMLInputElement> | Handler that is called when the element's value changes. You can pull out the new value by accessing event.target.value (string). |
| onValueChange | (value: string) => void | Handler that is called when the element's value changes. |
| onClear | () => void | Handler that is called when the clear button is clicked. |
| onHeightChange | (height: number, meta: { rowHeight: number }) => void | Handler that is called when the height of the textarea changes. |
