A Textarea is a form element that provides all the same features as the Text Input, but accepts multi-line text.

Usage

When to use

• As a form element that provides users with a way to read, input, or edit data in a multi-line field.

When not to use

• If needing a single-line input, consider TextInput.
• If needing to allow the user to make a selection from a predetermined list of options, consider Checkbox, Radio button, Select.

Required and optional

For complex forms, indicate required fields. This is the most explicit and transparent method and ensures users don’t have to make assumptions. Read more about best practices for marking required fields in forms.

For shorter, simpler forms (e.g., login/signup and feedback requests), indicate optional fields instead.

Marking required fields in forms

Character count

For tracking the number of characters entered into a Textarea and defining requirements around minimum and maximum length, refer to the Character count documentation.

Error validation

For error validation recommendations, refer to the Form patterns documentation.

Content

For high-level content recommendations, refer to our Primitives documentation.

How to use this component

There are two ways to use the Textarea component:

• Form::Textarea::Base - the base component: the <Textarea> Ember component.
• Form::Textarea::Field - the field parent component: the <Textarea> Ember component, with label, helper text and error messaging (in a wrapping container).

We recommend using the Field component because it provides built-in accessibility functionality. Use the Base component if needing to achieve custom layouts or have special use cases not covered by the Field component.

Form::Textarea::Field

The basic invocation requires a Label. This creates:

• a <label> element with a for attribute automatically associated with the textarea ID attribute.
• a <textarea> control with an automatically generated ID attribute.

<Hds::Form::Textarea::Field as |F|>
  <F.Label>Short description</F.Label>
</Hds::Form::Textarea::Field>

Textarea value

Pass a @value argument to pre-populate the textarea.

<Hds::Form::Textarea::Field @value="This is my description" as |F|>
  <F.Label>Short description</F.Label>
</Hds::Form::Textarea::Field>

Helper text

You can add extra information to the field using helper text. When helper text is added, the component automatically adds an aria-describedby attribute to the textarea control, associating it with the automatically generated ID of the helper text element.

<Hds::Form::Textarea::Field @value="This is my description" as |F|>
  <F.Label>Short description</F.Label>
  <F.HelperText>Add a short description about the workspace you are creating.</F.HelperText>
</Hds::Form::Textarea::Field>

Extra content in label and helper text

The Label and HelperText contextual components used in the Field component yield their content. This means you can also pass structured content.

<Hds::Form::Textarea::Field as |F|>
  <F.Label>Short description <Hds::Badge @size="small" @text="Beta" /></F.Label>
  <F.HelperText>This is an experimental feature (<Hds::Link::Inline @href="#">read more</Hds::Link::Inline>).</F.HelperText>
</Hds::Form::Textarea::Field>

Required vs. optional

Use the @isRequired and @isOptional arguments to add a visual indication that the field is "required" or "optional".

<Hds::Form::Textarea::Field @isRequired={{true}} as |F|>
  <F.Label>Short description</F.Label>
  <F.HelperText>Add a short description about the workspace you are creating.</F.HelperText>
</Hds::Form::Textarea::Field>
<br />
<Hds::Form::Textarea::Field @isOptional={{true}} as |F|>
  <F.Label>Short description</F.Label>
  <F.HelperText>Add a short description about the workspace you are creating.</F.HelperText>
</Hds::Form::Textarea::Field>

Character count

If the user input needs to be limited to a certain number of characters, use @maxLength on a CharacterCount contextual component to guide the user in meeting the length requirements. This property does not restrict the users from entering characters over the limit. To define the maximum string length that the user can enter, set maxlength attribute on the associated input field.