Text Field

Common Input Field Features
Placeholder
Clear Button
Text Alignment
Prefix & Suffix
Min & Max Input Length
Pattern
Small Variant
Autoselect
Related Components

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

Open in a
new tab
TextField textField = new TextField();
textField.setLabel("Street Address");
textField.setValue("Ruukinkatu 2");
textField.setClearButtonVisible(true);
textField.setPrefixComponent(VaadinIcon.MAP_MARKER.create());
add(textField);

Common Input Field Features

Text Field includes all shared input field features.

See shared input field features

The features described here for Text Field are generally also available for other single-line text input components.

Placeholder

A placeholder is a short description of the expected input value. It is only shown when the text field is empty.

Open in a
new tab
TextField textField = new TextField();
textField.setPlaceholder("Search");
textField.setPrefixComponent(VaadinIcon.SEARCH.create());
add(textField);

Note that placeholders are not universal substitutes for labels, as they are 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 also risk being 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 next to a search button.

Fields with placeholders, but without labels, should also provide an invisible label using the aria-label attribute to ensure screen readers can access it.

Clear Button

The optional clear button clears the field’s current value. It is hidden while the field is empty. Clear buttons are useful for search and filter fields, where it is common for the user to want to clear the field value. In data entry forms they are typically unnecessary, however.

Open in a
new tab
TextField textField = new TextField();
textField.setClearButtonVisible(true);
textField.setValue("Value");
add(textField);

Text Alignment

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

Right aligned values are recommended for numerical values, when presented in vertical groups, as this makes it easier to interpret and compare values.

Open in a
new tab
TextField right = new TextField();
right.setValue("value");
right.addThemeVariants(TextFieldVariant.LUMO_ALIGN_RIGHT);

Note	Numeric fields Number Field is a better choice for certain numeric fields.

Prefix & Suffix

Open in a
new tab
TextField username = new TextField();
username.setPrefixComponent(VaadinIcon.USER.create());
username.setLabel("Username");
username.setValue("maverick");
add(username);

TextField email = new TextField();
email.setSuffixComponent(new Div(new Text("@example.com")));
email.setLabel("Email Address");
email.setValue("michael");
email.addThemeVariants(TextFieldVariant.LUMO_ALIGN_RIGHT);
email.setMaxLength(7);
add(email);

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 should not be used as a replacement for labels, except in cases like search fields, preferably combined with a placeholder.

Min & Max Input Length

These properties affect the smallest and largest number of characters a field accepts, by limiting text entry to the max length, and triggering a validation error if a shorter value shorter 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.

Open in a
new tab
TextField zipCode = new TextField();
zipCode.setMinLength(5);
zipCode.setMaxLength(5);
zipCode.getStyle().set("width", "6em");
zipCode.setLabel("Zip code");
add(zipCode);

TextField username = new TextField();
username.setMaxLength(16);
username.setHelperText("Max 16 characters");
username.setLabel("Username");
add(username);

In cases where the length requirements may not be clear to the user, it is recommended to provide this information, for example by using a helper.

Pattern

Defines the pattern (using regular expressions) that the input must adhere to, to prevent the user from entering an invalid value.

Open in a
new tab
TextField textField = new TextField();
textField.setPattern("^[+]?[(]?[0-9]{3}[)]?[-s.]?[0-9]{3}[-s.]?[0-9]{4,6}$");
textField.setHelperText("Format: +(123)456-7890");
textField.setLabel("Phone number");
add(textField);

The example above only allows input of numbers, parenthesis, dashes, and plus sign. In cases where the format requirements may not be clear to the user, it is recommended to provide this information, for example by using a helper.

Small Variant

The small theme variant can be used to make individual fields more compact.

Open in a
new tab
TextField defaultSize = new TextField();
defaultSize.setLabel("Default size");
defaultSize.setValue("Value");
add(defaultSize);

TextField smallSize = new TextField();
smallSize.addThemeVariants(TextFieldVariant.LUMO_SMALL);
smallSize.setLabel("Small size");
smallSize.setValue("Value");
add(smallSize);

Note	Avoid overuse Size variants should be used sparingly.

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

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

ON

Pointing device or keyboard navigation

Contents selected

OFF

Pointing device

Cursor placed where clicked

OFF

Keyboard navigation
Tab

Cursor at the end of the input value

OFF

Keyboard navigation
⇧ Tab

Contents selected^[1]

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

Component	Usage Recommendations
Text Area	Free-form multi-line text input, for text longer than what can typically fit on a single line.
Email Field	For email addresses.
Number Field	Only allows 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 Recommendations

Text Area

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

Email Field

For email addresses.

Number Field

Only allows numeric input.

Password Field

For securely entering passwords.

Combo Box

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