TextArea

TextArea is a multiline text input.

Aria docs Aria API Reference Report an issue Edit this page

default.tsx

<TextArea label="Description" placeholder="Type your message here" />

Installation

Install the following dependencies:

npm install react-aria-components

Copy and paste the following code into your project.

text-area.tsx

field.tsx

input.tsx

"use client";

import * as React from "react";
import { type VariantProps } from "tailwind-variants";
import { Field, type FieldProps } from "./field";
import { InputRoot, TextAreaInput, type inputStyles } from "./input";
import { TextFieldRoot, type TextFieldRootProps } from "./text-field";

type TextAreaProps = TextFieldRootProps &
  Omit<FieldProps, "children"> &
  Omit<VariantProps<typeof inputStyles>, "size"> & {
    prefix?: React.ReactNode;
    suffix?: React.ReactNode;
    isLoading?: boolean;
    loaderPosition?: "prefix" | "suffix";
    placeholder?: string;
  };
const TextArea = React.forwardRef<HTMLTextAreaElement, TextAreaProps>(
  (
    {
      className,
      placeholder,
      label,
      description,
      errorMessage,
      prefix,
      suffix,
      isLoading,
      loaderPosition = "suffix",
      isRequired,
      necessityIndicator,
      contextualHelp,
      ...props
    },
    ref
  ) => {
    return (
      <TextFieldRoot className={className} {...props}>
        <Field
          label={label}
          description={description}
          errorMessage={errorMessage}
          isRequired={isRequired}
          necessityIndicator={necessityIndicator}
          contextualHelp={contextualHelp}
        >
          <InputRoot
            prefix={prefix}
            suffix={suffix}
            isLoading={isLoading}
            loaderPosition={loaderPosition}
            multiline
          >
            <TextAreaInput ref={ref} placeholder={placeholder} />
          </InputRoot>
        </Field>
      </TextFieldRoot>
    );
  }
);
TextArea.displayName = "TextArea";

export type { TextAreaProps };
export { TextArea };

Update the import paths to match your project setup.

Usage

Use a TextArea to allow users to input a long string of free-form text.

Options

Prefix and suffix

To add additional context for the TextArea, use the prefix and suffix props.

prefix-and-suffix.tsx

<TextArea
  label="Comment"
  placeholder="type something here"
  prefix={<Emojis />}
  suffix={<Toolbar />}
/>

Label

A visual label can be provided for the TextArea using the label prop or a hidden label using aria-label prop.

label.tsx

<TextArea label="Description" />
<TextArea aria-label="Description" />

Description

An errorMessage can be supplied to a TextField, which will be displayed when the isInvalid prop is set to true.

description.tsx

<TextArea label="Description" description="Type your description" />

Contextual help

A ContextualHelp element may be placed next to the label to provide additional information or help about a text area.

contextual-help.tsx

<TextArea label="Bio" contextualHelp={<ContextualHelp />} />

Error message

An errorMessage can be supplied to a TextArea, which will be displayed when the isInvalid prop is set to true.

error-message.tsx

<TextArea 
  label="Comment"
  isInvalid
  errorMessage="You have exceeded the comment limit for one hour." 
/>

Loading

Use the isLoading prop to control the loading state of the TextArea. Use the loaderPosition prop to control the position of the loader.

loading.tsx

<TextArea isLoading loaderPosition="prefix" />
<TextArea isLoading loaderPosition="suffix" />

Disabled

Use the isDisabled prop to disable the TextArea.

disabled.tsx

<TextArea isDisabled />

ReadOnly

The isReadOnly boolean prop makes the TextArea's text content immutable. Unlike isDisabled, the text area remains focusable and the contents can still be copied.

read-only.tsx

<TextArea isReadOnly />

Required

Use the isRequired prop to mark the TextArea as required. Use the necessityIndicator prop to control the visual style of the required state.

required.tsx

<TextArea label="Description" isRequired necessityIndicator="icon" />

Uncontrolled

Use the defaultValue prop to set the default input value.

uncontrolled.tsx

<TextArea label="Essay" defaultValue="Roses are red, violets are blue." />

Controlled

Use the value and onChange props to control the value of the input.

controlled.tsx

const [inputValue, setInputValue] = React.useState("Roses are red, violets are blue.");
return (
  <TextArea
    label="Essay"
    value={inputValue}
    onChange={(text) => {
      setInputValue(text);
    }}
  />
);

Composition

If you need to customize things further, you can drop down to the composition level.

composition.tsx

<TextFieldRoot>
  <Label>Comment</Label>
  <InputRoot>
    <TextAreaInput />
  </InputRoot>
  <Description>Enter your comment.</Description>
</TextFieldRoot>

API Reference

Prop	Type	Default	Description
prefix	ReactNode	-	A visual to display before the input.
suffix	ReactNode	-	A visual to display after the input.
loaderPosition	"prefix" \| "suffix"	"suffix"	The loader position
label	ReactNode		The content to display as the label.
description	ReactNode		A description for the field. Provides a hint such as specific requirements for what to choose.
errorMessage	ReactNode \| (v: ValidationResult) => ReactNode		An error message for the field.
isLoading	boolean	-	Whether the TextField is in a pending state.
isInvalid	boolean	-	Whether the value is invalid.
isDisabled	boolean	-	Whether the input is disabled.
isReadOnly	boolean	-	Whether the input can be selected but not changed by the user.
isRequired	boolean	-	Whether user input is required on the input before form submission.
validate	(value: string) => ValidationError \| true \| null \| undefined	-	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
autoFocus	boolean	-	Whether the element should receive focus on render.
value	string	-	The current value (controlled).
defaultValue	string	-	The default value (uncontrolled).
autoComplete	string	-	Describes the type of autocomplete functionality the input should provide if any.
maxLength	number	-	The maximum number of characters supported by the input.
minLength	number	-	The minimum number of characters required by the input.
pattern	string	-	Regex pattern that the value of the input must match to be valid.
type	'text' \| 'search' \| 'url' \| 'tel' \| 'email' \| 'password' \| string & {}	-	The type of input to render.
inputMode	'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search'	-	Hints at the type of data that might be entered by the user while editing the element or its contents.
name	string	-	The name of the input element, used when submitting an HTML form.
validationBehavior	'native' \| 'aria'	'native'	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.
children	ReactNode \| (values: TextFieldRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string	-	The CSS className for the element.
style	CSSProperties \| (values: TextFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Event	Type	Description
onFocus	(e: FocusEvent<Target>) => void	Handler that is called when the element receives focus.
onBlur	(e: FocusEvent<Target>) => void	Handler that is called when the element loses focus.
onFocusChange	(isFocused: boolean) => void	Handler that is called when the element's focus status changes.
onKeyDown	(e: KeyboardEvent) => void	Handler that is called when a key is pressed.
onKeyUp	(e: KeyboardEvent) => void	Handler that is called when a key is released.
onChange	(value: T) => void	Handler that is called when the value changes.
onCopy	ClipboardEventHandler<HTMLInputElement>	Handler that is called when the user copies text.
onCut	ClipboardEventHandler<HTMLInputElement>	Handler that is called when the user cuts text.
onPaste	ClipboardEventHandler<HTMLInputElement>	Handler that is called when the user pastes text.
onCompositionStart	CompositionEventHandler<HTMLInputElement>	Handler that is called when a text composition system starts a new text composition session.
onCompositionEnd	CompositionEventHandler<HTMLInputElement>	Handler that is called when a text composition system completes or cancels the current text composition session.
onCompositionUpdate	CompositionEventHandler<HTMLInputElement>	Handler that is called when a new character is received in the current text composition session.
onSelect	ReactEventHandler<HTMLInputElement>	Handler that is called when text in the input is selected.
onBeforeInput	FormEventHandler<HTMLInputElement>	Handler that is called when the input value is about to be modified.
onInput	FormEventHandler<HTMLInputElement>	Handler that is called when the input value is modified.

Data attribute	Description
[data-disabled]	Whether the text field is disabled.
[data-invalid]	Whether the text field is invalid.
[data-readonly]	Whether the text field is read only.
[data-required]	Whether the text field is required.

Getting Started

Components

Buttons

Inputs

Menus and Selection

Dates

Colors

Drag and drop

Feedback

Layout

Data display

Navigation

Overlay

Hooks