Textarea

<>
  <Label htmlFor="message" required>Message (at least 120 characters)</Label>
  <TextArea onChange={()=>{}} aria-describedby="message_help_text" id="message" name="message" required />
  <HelpText id="message_help_text">Enter at least 120 characters</HelpText>
</>

A Textarea allows users to enter text on multiple lines. It is used with the Label and Help Text components.

A Textarea allows for any text to be entered and can't be restricted as other inputs can.

• Include a visible label on all form fields.
• Each label must use the htmlFor prop that equals the id of the associated textarea.
• Avoid placeholder text. It's not broadly supported by assistive technologies, doesn't display in older browsers, and dissapears from the field when a user enters text.
• Use 1 of 3 ways to label a form field:
  • Visible label with Label (preferred)
  • Visible label that's associated to the textarea with aria-labelledby
  • Label directly using aria-label
• Provide clear identification of required fields in the label or at the start of a form. If you use the required field indicator, include the form key at the start of the form.
  • Use the required prop to programatically indicate they are required to browsers.
• Use Help Text and an error icon to show inline error text on any field that errors to make it visually clear that the field changed.
• If the textarea has associated help text or error text, include the aria-describedby prop on the textarea. This should match the id of the help or error text.

The Textarea should include the base Textarea, along with supporting elements to compose a textarea field that gives the user the context they need to successfully fill it out:

• Label — Every form field should have a label. The label should indicate what should be entered into field.
• Required field indicator — If most of the fields on a form are optional, indicate the few that are required with text or a required indicator.
• Help Text — Text that's placed below the field to help users prevent an error and describe what makes the form field successful

<>
  <Label htmlFor="message" required>Message (at least 120 characters)</Label>
  <TextArea onChange={()=>{}} aria-describedby="message_help_text" id="message" name="message" required />
  <HelpText id="message_help_text">Enter at least 120 characters</HelpText>
</>

• Prefix/suffix text — Text that can be used as a prefix and/or suffix to the value that is entered. Use prefix/suffix to help users format text.
• Icon — Icons can be placed in the same area as the prefix and suffix text. Icons should trigger an action (e.g., clearing a field).

<>
  <Label htmlFor="short_bio" required>Short biography</Label>
  <TextArea onChange={()=>{}} id="short_bio" name="short_bio" insertBefore={<Text color="colorTextWeak" as="span" fontWeight="fontWeightSemibold">Bio</Text>} required />
</>

<>
  <Label htmlFor="body" required>Body copy</Label>
  <TextArea
    onChange={()=>{}}
    aria-describedby="body_help_text"
    id="body"
    name="body"
    placeholder="Ahoy, World"
    insertAfter={
      <Button variant="link">
        <InformationIcon decorative={false} size="sizeIcon20" title="Get more info" />
      </Button>
    }
  />
  <HelpText id="body_help_text">Enter text for the copy area</HelpText>
</>

By default, the textarea is not resizable by the user. To change this, add the prop resize='vertical'.

You may also provide a maxRows prop to limit how much the textArea grows. By default this value is 10.

<>
  <Label htmlFor="message" required>Message (at least 120 characters)</Label>
  <TextArea onChange={()=>{}} aria-describedby="message_help_text" id="message" name="message" resize="vertical" maxRows={5} required />
  <HelpText id="message_help_text">Enter at least 120 characters</HelpText>
</>

Change a form field to its error state and use Help Text to add an inline error if the value entered doesn't pass validation requirements.

The error Help Text is placed below the field to inform a user of any errors in their value. The error text should replace and repeat the help text. Review the error state pattern for guidance on writing error messages.

<>
  <Label htmlFor="text_error">Description</Label>
  <TextArea onChange={()=>{}} aria-describedby="text_error_help_text" id="text_error" name="text_error" hasError />
  <HelpText id="text_error_help_text" variant="error">Enter a description.</HelpText>
</>

Use a disabled form field to show users that they can't interact with the field.

<>
  <Label htmlFor="text_disabled" disabled>Description (disabled)</Label>
  <TextArea onChange={()=>{}} id="text_disabled" name="text_disabled" placeholder="Paste is a design system used to build accessible, consistent, and high quality customer experiences at Twilio. Paste is open source and contributions are welcome." disabled />
</>

Use a read-only form field when a field's value can't be changed, but users should be able to read or apply focus on the field. For example, use a read-only form field if a user needs to copy the value.

<>
  <Label htmlFor="text_readonly">Description (read-only)</Label>
  <TextArea onChange={()=>{}} id="text_readonly" name="text_readonly" readOnly value="Paste is a design system used to build accessible, consistent, and high quality customer experiences at Twilio. Paste is open source and contributions are welcome." />
</>

A textarea field must have at least a label and a textarea.

<>
  <Label htmlFor="details">Details</Label>
  <TextArea onChange={()=>{}} id="details" name="details" />
</>

Stack form fields vertically with $space-80 spacing between each field.

<>
  <Box marginBottom="space80">
    <Label htmlFor="header">Header</Label>
    <TextArea onChange={()=>{}} id="header" name="header" placeholder="Ahoy, World!" />
  </Box>
  <Box>
    <Label htmlFor="footer">Footer</Label>
    <TextArea onChange={()=>{}} id="footer" name="footer" placeholder="Bon voyage" />
  </Box>
</>

Avoid placing multiple form fields on the same horizontal row to help make it easier to scan a page vertically. Use the Grid component if you need to place form fields horizontally.

Labels should clearly describe the value being requested. They should be concise and descriptive, not instructional. To do this:

• Use Help Text to provide instruction if needed. For example, don't use "Enter the registration code on the back of your SIM card below" as label text. Instead, use "SIM registration code" as a label and "Find the registration code on the back of your SIM card" as help text.
• Avoid articles (like "a" and "the") and punctuation. For example, use "SIM registration code" rather than "The SIM registration code".

To support internationalization, avoid starting a sentence with the label and using the field to finish it since sentence structures vary across languages. For example, use "Call log expiration date" or "How long should logs be stored?". Don't use "Remove logs after:".

Give users enough information in help text to prevent textarea and formatting errors. Keep it concise and scoped to information that will help with validation. For example, use help text if a password field has specific requirements that a user should know prior to filling it out.

Ask for information only when needed. Consider removing the field otherwise.

Use text or required indicators to show users which fields they must fill out.

Validate form fields on form submission.

Validating a form field when the user leaves the current field (on blur) can be helpful to check for syntax errors. However, this can be frustrating to users who tab through controls to navigate a page, and to screen reader users, who might not be able to detect that an error occurred on blur.

Don't prevent form submission by disabling the submit button. A disabled button cannot be detected by assistive technologies. Use error messages to explain what information is missing or incorrect.

Use Help Text to show an inline error that to explains how to fix the error. For additional guidance on how to compose error messages, refer to the error state pattern.

• Prefix/suffix — Use a prefix or suffix to help users format their textarea and to provide more context about the value a user is entering. For example, you could prefix or suffix a field with a currency symbol, or use suffix to append a character counter. Make sure to consider internationalization when using prefixes or suffixes since formatting may differ across languages. For example, currency symbols are placed on the left in American English, while they're placed on the right in French. Don't use prefix/suffix text as a replacement for a label.
• Icon — Use an icon if you need to give the user additional controls for the field. For example, use an icon to clear a field on click, removing the need for users to manually delete their entered value. Place icon buttons that trigger an action on the right side of the field. If you need 2 actions on a field (e.g., popover trigger and clear field), place the icon button that affects the field value on the right, and the other icon on the left.

Use a textarea when users are expected to enter text that exceeds a single line, usually longer than a sentence.