Text Field
- Usage
- Styling
Text Field allows the user to input and edit text. Prefix and suffix components, such as icons, are also supported.
new tab
<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>
Common Input Field Features
Text Field includes all shared input field features.
The features described here for Text Field are also available for other single-line text input components.
Placeholder
A placeholder is a short description of the expected input value. It’s only shown when the text field is empty.
new tab
<vaadin-text-field placeholder="Search">
<vaadin-icon slot="prefix" icon="vaadin:search"></vaadin-icon>
</vaadin-text-field>
Placeholders aren’t universal substitutes for labels since they’re only visible while the field is empty. Helpers are a better way to provide information that the user may need when filling in the field. Unless marked as required, fields with placeholders might be inadvertently skipped when filling in a form.
Search fields are a good example of where placeholders can be used without a label, if they are prefixed or suffixed with a search icon or located next to a search button.
Fields with placeholders, but without labels, should also provide an invisible label using the aria-label
attribute to ensure that screen readers can access it.
Clear Button
The optional clear button clears the field’s current value. It’s hidden while the field is empty. Clear buttons are useful for search and filter fields, where users might sometimes want to clear the field value. However, in data entry forms, they’re typically unnecessary.
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. It makes it easier to interpret and compare values.
Note
|
Numeric fields
Number Field is often a better choice for certain numeric fields.
|
Prefix & Suffix
new tab
<vaadin-text-field label="Username" placeholder="username" value="maverick">
<vaadin-icon slot="prefix" icon="vaadin:user"></vaadin-icon>
</vaadin-text-field>
<vaadin-text-field
label="Email Address"
placeholder="name"
value="michael"
theme="align-right"
maxlength="7"
>
<div slot="suffix">@example.com</div>
</vaadin-text-field>
Prefixes and suffixes can be used to display currency, units, icons, etc. Text or icons are recommended, but other elements can be used as well — if they fit into the field.
Prefixes and suffixes shouldn’t be used as a replacement for labels. The exception, though, would be fields like search fields, preferably combined with a placeholder.
Note
|
Prefix and suffix are ignored by screen readers
Any information relevant for assistive technologies needs to be provided as a label and possibly helper text.
|
Min & Max Input Length
These properties affect the smallest and largest number of characters a field accepts, by limiting text entry to the maximum length, and triggering a validation error if a shorter value than the minimum length is entered. They can be used to enforce specific value formats, or to cap the value to the longest length supported by the underlying database schema.
new tab
<vaadin-text-field
minlength="5"
maxlength="5"
label="Zip code"
style="width: 6em"
></vaadin-text-field>
<vaadin-text-field
label="Username"
helper-text="Max 16 characters"
minlength="1"
maxlength="16"
></vaadin-text-field>
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 that the Text Field’s complete value is matched against during validation. Any value that doesn’t match the pattern invalidates the field.
The following example invalidates any value that doesn’t consist exclusively of numbers, parentheses, dashes, and the plus sign:
new tab
<vaadin-text-field
pattern="^[+]?[(]?[0-9]{3}[)]?[-s.]?[0-9]{3}[-s.]?[0-9]{4,6}$"
label="Phone number"
helper-text="Format: +(123)456-7890"
></vaadin-text-field>
In cases where the format requirements may not be clear to the user, it’s recommended to provide this information, for example by using a helper.
Preventing Entry of Invalid Characters
Individual characters that the user enters into Text Field can be restricted using a single-character regular expression. When enabled, the user can only enter characters that match the regular expression. If they try to enter any other characters, the component gives visual feedback that the input was prevented.
The following example shows how to let the user enter only numbers, parentheses, dashes, and the plus sign:
new tab
<vaadin-text-field
allowed-char-pattern="[\\d\\-+()]"
label="Phone number"
helper-text="Format: +(123)456-7890"
></vaadin-text-field>
Small Variant
The small theme variant can be used to make individual fields more compact.
new tab
<vaadin-text-field theme="small" label="Small size" value="Value"></vaadin-text-field>
Note
|
Avoid overuse
Size variants should be used sparingly. See Size and Space for details on how to change the default text field size.
|
Autoselect
When a field is set to autoselect
, its contents are selected when the field is focused. Use autoselect
when the user might to want to replace the entire value rather than tweak it.
Autoselect | Focused with | Result |
---|---|---|
| Pointing device or keyboard navigation | Contents selected |
| Pointing device | Cursor placed where clicked |
| Keyboard navigation | Cursor at the end of the input value |
| Keyboard navigation | Contents selected[1] |
Related Components
A variety of components are available for different types of input:
Component | Usage Recommendations |
---|---|
Free-form multi-line text input, for text longer than can typically fit on a single line. | |
For email addresses. | |
Allows only numeric input. | |
For securely entering passwords. | |
For selecting from a predefined set of options. Allows filtering and entering custom values. | |
Input field for entering or selecting a specific date. | |
Input field for entering or selecting a specific time. |
E6D6D93F-BDB7-425A-AE47-343981004746