Text Area
- Usage
- Styling
Text Area is an input field component that allows entry of multiple lines of text.
new tab
<vaadin-text-area
label="Comment"
.maxlength="${this.charLimit}"
.value="${this.text}"
.helperText="${`${this.text.length}/${this.charLimit}`}"
@value-changed="${(event: TextAreaValueChangedEvent) => {
this.text = event.detail.value;
}}"
></vaadin-text-area>Text Area is typically used for descriptions, comments, and other longer free-form content.
Automatic Height Adjustment
Unless set to a fixed height, Text Area adjusts its height automatically based on its content. The default and minimum height is two rows of text.
new tab
<vaadin-text-area label="Description" value="${templates.loremIpsum}"></vaadin-text-area>Minimum & Maximum Height
The automatic resizing can be restricted to a minimum and maximum height like so:
new tab
<style>
vaadin-text-area {
width: 100%;
min-height: 100px;
max-height: 150px;
}
</style>
<vaadin-text-area label="Description" value="${templates.loremIpsum}"></vaadin-text-area>Basic Features
The following features, common to most input field components, are supported:
Label
The label is used to identify the input field. It supports plain-text content, and its length is limited to the width of the field. Helpers and Tooltips can be used to provide additional information that doesn’t fit into the label.
Visible labels are strongly recommended for all input fields. In cases where the built-in label cannot be used, an external element can be associated as the field’s label through the aria-labelledby attribute. Fields without any visible label should include an invisible label for assistive technologies with the aria-label attribute.
Helper
Helpers are used to provide additional information that the user may need to enter in the field, such as format requirements or explanations of the field’s purpose below the field.
A style variant is available for rendering the helper above the field.
In addition to plain text, helpers can contain components and HTML elements. However, complex and interactive content is likely to have accessibility issues.
Placeholder
The placeholder is text that’s displayed when the field is empty. Its primary purpose is to provide a short input hint (e.g., the expected format) in situations where a Helper cannot be used.
Placeholders should not be used as a replacement for a visible label. They can be mistaken for a manually entered value. See Label for alternatives to the built-in field label.
Tooltip
Tooltips are small text pop-ups displayed on hover, and on keyboard-focus. They can be used to provide additional information about a field. This can be useful in situations where an always visible Helper is not appropriate. Helpers are generally recommended in favor of tooltips, though, as they provide much better discoverability and mobile support. See the Tooltip documentation for more information.
Prefix & Suffix
Prefix and suffix elements — rendered at either end of the field — can be used to display units, icons, and similar visual cues to the field’s purpose or format.
External & Invisible Labels (ARIA)
Visible labels are strongly recommended for all input fields. In situations where the built-in label cannot be used, an external element can be associated as the field’s label through its element id. Fields without any visible label should be provided an invisible label for assistive technologies like screen readers.
<!-- Associates external element as label: -->
<label id="external-label">This is the label</label>
<vaadin-text-area accessible-name-ref="external-label">...
<!-- Invisible label for screen readers: -->
<vaadin-text-area accessible-name="This is the label">...new tab
<vaadin-text-area
label="Label"
helper-text="Helper text"
placeholder="Placeholder"
clear-button-visible
style="width:100%"
>
<vaadin-tooltip slot="tooltip" text="Tooltip text"></vaadin-tooltip>
<vaadin-icon slot="prefix" icon="vaadin:vaadin-h"></vaadin-icon>
<span slot="suffix">:)</span>
</vaadin-text-area>Validation
Text Area provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation occurs typically when the user initiates a value change, for example by entering input and pressing Enter. If the value is invalid, the field is highlighted in red, and an error message appears underneath the input. Certain constraints, however, can proactively prevent users from entering characters that would result in an invalid value.
Below is a list of supported constraints with more detailed information:
Required
Required fields are marked with an indicator next to the label, and become invalid if their value is first entered and then cleared.
An instruction text at the top of the form explaining the required indicator is recommended. The indicator itself can be customized with the --lumo-required-field-indicator style property.
Min & Max Length
The minimum and maximum input length value constraints dictate the smallest, and the largest number of characters a field accepts. It triggers a validation error if a value shorter than the minimum length is entered, and limits text entered to the maximum length. They can be used to enforce specific formats, or to cap the value to the length supported by the underlying database schema.
In cases where the length requirements may not be clear to the user, it’s recommended to provide this information, for example by using a Helper.
Pattern
The pattern is a regular expression used to validate the full value entered into the field. Any value that doesn’t match the pattern, invalidates the field.
Allowed Characters
A separate single-character, regular expression can be used to restrict the characters that can be entered into the field. Characters that don’t match the expression are rejected. However, values set programmatically are not subject to this restriction, even if they contain disallowed characters.
new tab
<vaadin-text-area
required
minlength="5"
maxlength="50"
pattern="^[A-Z]([A-Za-z0-9,-\\s])*\\.$"
allowed-char-pattern="[A-Za-z0-9,.\\-\\s]"
label="Sentence"
helper-text="Must be one complete sentence ending in a period, between 5 and 50 characters long"
style="width:100%"
.errorMessage="${this.errorMessage}"
@validated="${(event: TextAreaValidatedEvent) => {
const field = event.target as TextArea;
const { validity } = field.inputElement as HTMLTextAreaElement;
if (validity.valueMissing) {
field.errorMessage = 'Field is required';
} else if (validity.tooShort) {
field.errorMessage = `Minimum length is ${field.minlength} characters`;
} else if (validity.tooLong) {
field.errorMessage = `Maximum length is ${field.maxlength} characters`;
} else if (!new RegExp(field.pattern).test(field.value)) {
field.errorMessage = 'Must be one complete sentence ending in a period';
} else {
field.errorMessage = '';
}
}}"
></vaadin-text-area>It’s important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback.
Read-Only & Disabled
Fields used to display values should be set to read-only mode to prevent editing. Read-only fields are focusable and visible to screen readers. They can display tooltips. Their values can be selected and copied.
Fields that are currently unavailable should be disabled. The reduced contrast of disabled fields makes them inappropriate for displaying information. They can’t be focused or display tooltips. They’re invisible to screen readers, and their values cannot be selected and copied.
Disabled fields can be useful in situations where they can become enabled based on some user action. Consider hiding fields entirely if there’s nothing the user can do to make them editable.
new tab
<vaadin-text-area readonly label="Read-only" value="Value" style="width:100%">
</vaadin-text-area>
<vaadin-text-area disabled label="Disabled" style="width:100%"></vaadin-text-area>Style Variants
The following style variants can be applied:
Text Alignment
Three different text alignments are supported: left, which is the default; center; and right.
Right-alignment is recommended for numerical values when presented in vertical groups. This tends to aid interpretation and comparison of values.
Small Variant
The small variant can be used to make individual fields more compact. The default size of fields can be customized with style properties.
Helper Above Field
The helper can be rendered above the field, and below the label.
Borders
Borders can be applied to the field surface by providing a value (e.g., 1px) to the --vaadin-input-field-border-width CSS property. This can be applied globally to all input fields using the html selector, or to individual component instances. Borders are required to achieve WCAG 2.1 level AA conformant color contrast with the default Lumo styling of fields.
You can override the default border color with the --vaadin-input-field-border-color property.
new tab
<vaadin-text-area
theme="align-right small helper-above-field"
label="Label"
helper-text="Helper text"
value="Value"
style="--vaadin-input-field-border-width: 1px; width: 100%;"
></vaadin-text-area>Character Counter
Longer free-form inputs are often capped at a certain character limit. The current character count and upper limit should be displayed to the user, for example by using the Helper feature:
new tab
private charLimit = 600;
@state()
private text = templates.loremIpsum;
protected override render() {
return html`
<vaadin-text-area
label="Description"
.maxlength="${this.charLimit}"
.value="${this.text}"
.helperText="${`${this.text.length}/${this.charLimit}`}"
@value-changed="${(event: TextAreaValueChangedEvent) => {
this.text = event.detail.value;
}}"
></vaadin-text-area>
`;
}