Text Area

TextAreaV2 is built on React Aria and styled with Thumbprint v2 semantic tokens. Like v1 it is a controlled component: the visible text always matches the value prop, and onChange hands back the new value so you can store it in state.

The field also renders its own label and helper text. Prefer the label, description, and errorMessage props over composing Label and FormNote siblings: React Aria generates the ids and wires up the label association and aria-describedby, so the field is accessible with no ids to keep unique and no way for the error styling and the error text to fall out of sync.

The label prop renders the label above the textarea and associates the two for assistive technologies. Every field needs a label; when the design has no room for a visible one, pass accessibilityLabel instead.

function TextAreaExample() {
    const [value, setValue] = React.useState('');

    return (
        <TextAreaV2
            label="Project details"
            value={value}
            placeholder="Tell us about your project"
            onChange={setValue}
        />
    );
}

The description prop renders helper text below the textarea and points the textarea’s aria-describedby at it, so screen readers announce it along with the label.

function TextAreaExample() {
    const [value, setValue] = React.useState('');

    return (
        <TextAreaV2
            label="Project details"
            description="The more you share, the more accurate your quotes will be."
            value={value}
            placeholder="Tell us about your project"
            onChange={setValue}
        />
    );
}

The errorMessage prop puts the textarea in the error state — there is no separate hasError to remember — and renders the message below it. It replaces the description while the error is showing, so you can pass both and let the field swap them.

The error state is visual only, as it was in v1: it sets aria-invalid but leaves native validity alone, so a <form> holding an errored textarea still submits and your own validation stays in charge. isRequired is unaffected — it still applies the native required attribute, which the browser does enforce.

function TextAreaExample() {
    const [value, setValue] = React.useState('Help');
    const errorMessage =
        value.length < 20 ? 'Please describe your project in at least 20 characters.' : undefined;

    return (
        <TextAreaV2
            label="Project details"
            description="The more you share, the more accurate your quotes will be."
            errorMessage={errorMessage}
            value={value}
            onChange={setValue}
        />
    );
}

hasError turns the label, text, and border red without rendering a note. Use it only when the message lives elsewhere — such as a summary at the top of the form — since an error state with no explanation leaves users stuck.

function TextAreaExample() {
    const [value, setValue] = React.useState('Help');

    return <TextAreaV2 label="Project details" hasError value={value} onChange={setValue} />;
}

The isDisabled prop disables the textarea visually and functionally, and dims the built-in label along with it.

function TextAreaExample() {
    const [value, setValue] = React.useState('Repaint two bedrooms and the upstairs hallway.');

    return <TextAreaV2 label="Project details" isDisabled value={value} onChange={setValue} />;
}

The isReadOnly prop adds the readonly attribute, letting users focus and select the text without editing it. There is no separate read-only look, and read-only textareas are still submitted with the form, so an errorMessage on one still shows. A disabled textarea is the opposite: it keeps the disabled treatment and its error is not shown, since the browser skips disabled fields when submitting.

function TextAreaExample() {
    const [value, setValue] = React.useState('Repaint two bedrooms and the upstairs hallway.');

    return <TextAreaV2 label="Project details" isReadOnly value={value} onChange={setValue} />;
}

The maxLength prop caps the number of characters the browser accepts; onChange stops firing once the limit is reached. Say what the limit is in the description so it isn’t a surprise.

function TextAreaExample() {
    const [value, setValue] = React.useState('');

    return (
        <TextAreaV2
            label="Project details"
            description="Up to 60 characters."
            maxLength={60}
            value={value}
            placeholder="Tell us about your project"
            onChange={setValue}
        />
    );
}

For call sites that have not moved to the props yet, a sibling Label and FormNote still work: the id prop lands on the <textarea> element, so Label’s for associates the two natively. You are then responsible for keeping the ids unique and, in the error state, for keeping the hasError flags on all three components in sync — which is why the label, description, and errorMessage props are the better choice for new code.

In development, React Aria logs a console warning for this pattern because it can’t detect the external for/id association. The association is real and accessible, so the warning can be ignored; passing label or accessibilityLabel silences it.

function TextAreaExample() {
    const [value, setValue] = React.useState('');

    return (
        <div>
            <Label for="example-text-area-v2">Project details</Label>
            <TextAreaV2
                id="example-text-area-v2"
                value={value}
                placeholder="Tell us about your project"
                onChange={setValue}
            />
            <div className="mt1">
                <FormNote>The more you share, the more accurate your quotes will be.</FormNote>
            </div>
        </div>
    );
}