Text Field

Usage
Styling

Text Field allows the user to input and edit text. Prefix and suffix components, such as icons, are also supported.

<vaadin-text-field label="Street Address" value="Ruukinkatu 2" clear-button-visible>
  <vaadin-icon slot="prefix" icon="vaadin:map-marker"></vaadin-icon>
</vaadin-text-field>

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.

Helper

Helpers are used to provide additional information that the user may need to fill 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 other HTML elements. However, complex and interactive content are likely to have accessibility issues.

Placeholder

The placeholder is a text that is displayed when the field is empty. Its primary purpose is to provide a short input hint, such as the expected format, in cases where a Helper cannot be used.

Placeholders should not be used as a replacement for a visible label. See Label for alternatives to the built-in field label. Be aware that placeholders can be mistaken for a filled-in value.

Clear Button

The optional clear button, displayed when the field is not empty, clears the field’s current value. Clear buttons can be especially useful in search and filter fields, where users often need to clear the value, but less so in regular forms.

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.

Prefix and suffix elements typically don’t work well with assistive technologies like screen readers. Therefore, the information conveyed by them should also be conveyed through other means, such as in the Label, a Helper or through ARIA attributes on the field itself.

External and Invisible Labels (ARIA)

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 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-field accessible-name-ref="external-label">...

<!-- Invisible label for screen readers: -->
<vaadin-text-field accessible-name="This is the label">...

Open in a
new tab

<vaadin-text-field
  label="Label"
  helper-text="Helper text"
  placeholder="Placeholder"
  clear-button-visible>
  <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-field>

Constraints

Required

Required fields are marked with an indicator next to the label, and become invalid if left empty after having been focused. An error message explaining that the field is required needs to be provided manually.

An instruction text at the top of the form explaining the required indicator is recommended. The indicator itself can be customized through the --lumo-required-field-indicator style property.

Min & Max Input Length

The minimum and maximum length value constraints dictate the smallest and largest number of characters a field accepts. It limits text entry to the maximum length, and triggers a validation error if a value shorter than the minimum length is entered. 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.

Preventing Entry of Invalid 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.

Open in a
new tab

<vaadin-text-field
  required
  min-length="5"
  max-length="18"
  pattern="^[+]?[(]?[0-9]{3}[)]?[-s.]?[0-9]{3}[-s.]?[0-9]{4,6}$"
  allowed-char-pattern="[0-9()+-]"
  label="Phone number"
  helper-text="Format: +(123)456-7890"
></vaadin-text-field>

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 is nothing the user can do to make them editable.

Open in a
new tab

<vaadin-text-field readonly label="Read-only" value="Value">
</vaadin-text-field>

<vaadin-text-field disabled label="Disabled">
</vaadin-text-field>

Style Variants

The following style variants can be applied:

Text Alignment

Three different text alignments are supported: left (default), center, and right.

Right-alignment is recommended for numerical values when presented in vertical groups, as it aids 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 through style properties.

Helper Above Field

The helper can be rendered above the field, below the label.

Open in a
new tab

<vaadin-text-field theme="align-right small helper-above-field"
  label="Label" helper-text="Helper text" value="Value">
</vaadin-text-field>

Autoselect

When a field is set to autoselect, its content is selected when the field is focused. Use autoselect when the user might to want to replace the entire value rather than adjust it.

Autoselect Focused with Result

Autoselect	Focused with	Result
`ON`	Pointing device or keyboard navigation.	Content selected.
`OFF`	Pointing device.	Cursor placed where clicked.
`OFF`	Keyboard navigation `Tab`	Cursor at the end of the input value.
`OFF`	Keyboard navigation `Shift`+`Tab`	Contents selected^[1]

ON

Pointing device or keyboard navigation.

Content selected.

OFF

Pointing device.

Cursor placed where clicked.

OFF

Keyboard navigation
Tab

Cursor at the end of the input value.

OFF

Keyboard navigation
Shift+Tab

Contents selected^[1]

A variety of components are available for different types of input:

Component	Usage Recommendation
Text Area	Free-form multi-line text input, for text longer than can typically fit on a single line.
Email Field	For email addresses.
Number Field	Allows only numeric input.
Password Field	For securely entering passwords.
Combo Box	For selecting from a predefined set of options. Allows filtering and entering custom values.
Date Picker	Input field for entering or selecting a specific date.
Time Picker	Input field for entering or selecting a specific time.

Component

Usage Recommendation

Text Area

Free-form multi-line text input, for text longer than can typically fit on a single line.

Email Field

For email addresses.

Number Field

Allows only numeric input.

Password Field

For securely entering passwords.

Combo Box

For selecting from a predefined set of options. Allows filtering and entering custom values.