Textarea

<gr-textarea> | GrTextarea

Textarea can be used in forms, or anywhere where the user needs to provide information. It allows multiple lines of text.

Unlike the native textarea element, the Graphite textarea does not support loading its value from the inner content. The textarea value should be set in the value attribute.

<gr-textarea label="Feedback"></gr-textarea>

Options

Rows

Use the rows attribute to change the number of text rows that get shown.

<gr-textarea rows="2"></gr-textarea>

Placeholders

Use the placeholder attribute to add a placeholder.

The placeholder text, also commonly known as “ghost text,” is temporary and disappears once a user enters text.

Putting instructions for how to complete a textarea, requirements, or any other essential information into placeholder text is not accessible. Once a value is entered, this text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text. Help text is the preferred way to communicate this information.

<gr-textarea placeholder="Type something"></gr-textarea>

Disabled

Use the disabled attribute to disable an input.

<gr-textarea placeholder="Textarea" disabled></gr-textarea>

Sizes

Use the size attribute to change a textarea's size.

<gr-textarea placeholder="Small" size="small"></gr-textarea>
<br />
<gr-textarea placeholder="Medium" size="medium"></gr-textarea>
<br />
<gr-textarea placeholder="Large" size="large"></gr-textarea>

Invalid

The textarea can be marked invalid using the invalid attribute.

<gr-textarea placeholder="Invalid" invalid></gr-input>

Labels

Use the label attribute to give the textarea an accessible label. For labels that contain HTML, use the label slot instead.

<gr-textarea label="Comments"></gr-textarea>

Required or optional

Textareas can be marked as optional or required, depending on the situation. For required textareas, there are two styling options: a “(required)” label or an asterisk with the required-indicator attribute. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional textareas are either denoted with text added to the end of the label — “(optional)” — or have no indication at all.

The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself.

<gr-textarea label="Interests (required)" value="Photography, gardening"></gr-textarea>
<br />
<gr-textarea label="Interests (optional)" value="Photography, gardening"></gr-textarea>
<br />
<gr-textarea label="Interests" value="Photography, gardening" required-indicator></gr-textarea>

Help Text

Add descriptive help text to a textarea with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.

<gr-textarea label="Feedback" help-text="Please tell us what you think."></gr-textarea>

Invalid Text

Add descriptive invalid text to a textarea with the invalid-text attribute. For invalid texts that contain HTML, use the invalid-text slot instead.

When you add the invalid attribute, the invalid text will be shown. When a textarea already includes help text, the help text is replaced with invalid text.

<gr-textarea
  label="Feedback"
  help-text="Please tell us what you think."
  invalid-text="Tell us what you think."
  invalid
></gr-textarea>

Prevent Resizing

By default, textareas can be resized vertically by the user (in desktop browsers). To prevent resizing, set the resize attribute to none.

<gr-textarea resize="none"></gr-textarea>

Expand with Content

Textareas will automatically resize to expand to fit their content when resize is set to auto.

<gr-textarea resize="auto"></gr-textarea>

Usage guidelines

Include a label

Every textarea should have a label. A textarea without a label is ambiguous and not accessible.

Follow capitalization rules

Textarea labels and placeholder text should be in sentence case.

Mark the minority of fields in a form as optional or required

In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. If most of the fields are optional, only the required fields should be give an asterisk or have labels appended with “(required)”. If most of the fields are required, only the optional fields should be appended with “(optional)”. An asterisk should never be used to note that a field is optional. If you use an asterisk, be sure to include hint text to explain what the asterisk means.

Try to only ask for information that’s required.

For large forms involving sensitive data like checkout processes and long account creation forms, it's better to mark both required fields & optional fields explicitly (required fields with an asterisk, and label appended with “(optional)” for optional fields).

Use help text to show hints, formatting, and requirements

The description in the help text is flexible and encompasses a range of guidance. Sometimes this guidance is about what to input, and sometime it’s about how to input. This includes information such as:

• An overall description of the input field
• Hints for what kind of information needs to be input
• Specific formatting examples or requirements

The help text’s message should not simply restate the same information in the label in order to prompt someone to interact with it. Don’t add help text if it isn’t actually relevant or meaningful to a user in order to try to maintain layout continuity with other inputs that require help text.

Use help text instead of placeholder text

Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible, and should be avoided if possible. Once a value is entered, placeholder text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text.

Instead of placeholder text, use the help text description to convey requirements or to show any formatting examples that would help user comprehension. If there's placeholder text and help text at the same time, it becomes redundant and distracting, and especially if they're communicating the same thing.

Validation

We recommend validating the users data before form submission. Use visual cues to guide the user as to where the problem lies within the form. This will help to easily identify the elements that need to be corrected.

The validation should appear when the user has clicked away from the textarea (not before), or otherwise when the user submits the form. Once the user corrects the errors within the textarea, the validation should disappear once the data is rendered as valid.

For Vue, we recommend Vuelidate to implement this behavior. See a working example (CodeSandbox).

Of course, you should still validate server-side (if applicable).

Always write invalid text when invalid

Don't just mark an input invalid and expect the user to understand why it's invalid. Furthermore, the invalid text displays an icon which is needed for accessibility, and gives more attention to the invalid field.

Switch help text with invalid text

The help text area also displays an error message. When a text field already includes help text and it's marked invalid, the help text is replaced with invalid text. Once it's no longer invalid, the help text description reappears below the field.

Since one gets replaced by the other, the language of the help text and invalid text need to work together to convey the same messaging. Help text explains the requirement or adds supplementary context for how to successfully complete the input. Invalid text tells a user how to make it valid by re-stating the input requirements or describing the necessary interaction. Make sure that the help text and the invalid text include the same essential information so that it isn’t lost if one replaces the other (e.g., password requirements).

Write invalid text that shows a solution

Write error messaging in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user.

Invalid text should be written in 1-2 short, complete sentences and in a clear and straightforward way. End sentences with a period, and never with an exclamation point. For textareas, the nature of the error is often related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss filling out a required field that asks for their interests, write the invalid text like you’re offering a hint or a tip to help guide them to understand what needs to go in the missing field: “Enter at least one interest.”

Properties

Events

Methods

removeFocus() => Promise<void>

Removes focus fromt the textarea.

Returns

Type: Promise<void>

select() => Promise<void>

Selects all the text in the input.

Returns

Type: Promise<void>

setFocus(options?: FocusOptions) => Promise<void>

Sets focus on the textarea.

Returns

Type: Promise<void>

setRangeText(replacement: string, start: number, end: number, selectMode?: 'select' | 'start' | 'end' | 'preserve') => Promise<void>

Replaces a range of text with a new string.

Returns

Type: Promise<void>

setSelectionRange(selectionStart: number, selectionEnd: number, selectionDirection?: 'forward' | 'backward' | 'none') => Promise<void>

Sets the start and end positions of the text selection (0-based).

Returns

Type: Promise<void>

Slots

CSS custom properties