Textarea

import { ... } from '@ag.ds-next/react/textarea';

<Textarea label="Message" />

By default, the Textarea component does not expand to fill the available space.

Do

• use for plain text descriptions and messages
• include help text above the input box
• include a clear label that tells users what information is required
• use for collecting multi-line plain text values
• use when asking for a description or feedback
• allow the user to use the resize handle
• specify if there is a maximum input length
• indicate if input is optional.

Don’t

• use when a specific value is needed
• use for inputs that expect a single value or a couple of words.

Hint

Use the hint prop to provide help that’s relevant to the majority of users, like how their information will be used, or where to find it.

Don’t use long paragraphs and lists in hint text. Screen readers read out the entire text when users interact with the form element. This could frustrate users if the text is long.

Don’t include links within hint text. While screen readers will read out the link text when describing the field, they will not tell users that the text is a link.

<Textarea label="Message" hint="Hint text" />

Required

The required prop can be used to indicate that user input is required on the field before a form can be submitted.

Required fields do not append ‘(optional)’ to the label and also use aria-required to indicate to screen readers that the field is required.

Hide optional label

The hideOptionalLabel prop can be used in situations where you want to indicate to screen reader users that a field is optional but don’t want to show the ‘(optional)’ label.

The usage of hideOptionalLabel should be reserved for inputs that filter data in a table or chart, and should never be used in standard forms for submitting information.

<Stack gap={1}>
	<Textarea label="Required" required />
	<Textarea label="Optional" required={false} />
	<Textarea
		label="Optional with hideOptionalLabel"
		required={false}
		hideOptionalLabel={true}
	/>
</Stack>

Invalid

Use the invalid prop to indicate if the user input is invalid.

<Textarea label="Invalid" invalid message="This field is invalid" />

Disabled

Disabled textarea elements are unusable and can not be clicked. This prevents a user from interacting with the textarea element until another action is complete. Disabled textarea elements in a form will not be submitted.

<Textarea label="Message" disabled />

Maximum widths

The maximum width of a textarea should indicate the amount of information expected to be entered into the field. The size of the textarea acts as a visual constraint for the end user.

<Stack gap={1}>
	<Textarea label="md textarea" maxWidth="md" />
	<Textarea label="lg textarea" maxWidth="lg" />
	<Textarea label="xl textarea" maxWidth="xl" />
</Stack>

Block

Use the block prop to expand the component to fill the available space.

<Textarea label="Message" block />

Related components

• Text input – This component allows users to enter free-form text.