Input Fields

Label
Helper
Required
Non-Editable Fields
Focus
Input Field Components

The following features are available in all input field components.

Label

An input field should generally have a label for identifying it. Labels should be clear, concise, and written in sentence case. Avoid unclear and verbose language. Use helper texts to provide more guidance.

Open in a
new tab

EmailField emailField = new EmailField();
emailField.setLabel("Email address");
add(emailField);

In situations where enough context is provided, such as grid filters and search fields, labels can be omitted; in these cases an aria-label attribute should be provided instead to identify the field, so that users of assistive technologies can interpret the input correctly. Icons and placeholders can be used in addition to a label or aria-label to help convey a field’s purpose and usage:

Open in a
new tab

TextField textField = new TextField();
textField.getElement().setAttribute("aria-label", "search");
textField.setPlaceholder("Search");
textField.setClearButtonVisible(true);
textField.setPrefixComponent(VaadinIcon.SEARCH.create());
add(textField);

Helper

Helpers provide information when needed so that end users can fill in a form or field without errors. They are helpful, for example, when the field requires a specific format. Helpers typically consist of plain text but HTML and other components are also supported.

Open in a
new tab

TextField textField = new TextField();
textField.setLabel("Phone number");
textField.setHelperText("Include country and area prefixes");

PasswordField passwordField = new PasswordField();
passwordField.setLabel("Password");
passwordField.setRevealButtonVisible(false);

checkIcon = VaadinIcon.CHECK.create();
checkIcon.setVisible(false);
passwordField.setSuffixComponent(checkIcon);

Div passwordStrength = new Div();
passwordStrengthText = new Span();
passwordStrength.add(new Text("Password strength: "), passwordStrengthText);
passwordField.setHelperComponent(passwordStrength);

add(textField);
add(passwordField);

Helpers are preferable to tooltips since the latter are not accessible by assistive technologies such as screen readers nor available for touch screen users.

Helper Position

The helper can be shown above the field.

Open in a
new tab

TextField textField = new TextField();
textField.setLabel("Phone number");
textField.setHelperText("Include country and area prefixes");
textField.addThemeVariants(TextFieldVariant.LUMO_HELPER_ABOVE_FIELD);
textField.setWidth("15em");
add(textField);

Showing the helper before the field can be a better choice. It is more likely to be visible on small viewport sizes when the field is focused, and screen reader users can read the instructions before entering the field.

Use the same helper position across the entire application for consistency.

Required

Input fields can either be optional or required. Optional fields are typically left unmarked. In the default theme, required fields are marked with a bullet character. It’s recommended to provide hint text to inform users of how required fields are marked:

Open in a
new tab

TextField textField = new TextField();;
textField.setLabel("Name");
textField.setRequiredIndicatorVisible(true);
textField.setErrorMessage("This field is required");

DatePicker datePicker = new DatePicker();
datePicker.setLabel("Date of birth");

add(textField, datePicker);

The required indicator is only shown when the field is empty.

Marking Required & Optional Fields

If most of the fields in a form are optional, mark the required ones. When a form has more required than optional fields, mark the optional ones by adding a “(optional)” suffix to their labels.

A consistent experience is key to providing a good user experience, so be careful not to mix but rather match whether optional or required fields are marked in different forms.

Non-Editable Fields

In some cases, the user is not allowed to edit the value of certain fields. Those fields can read-only or disabled. Choose the suitable one depending on the situation.

Read-Only

Open in a
new tab

TextField textField = new TextField();
textField.setReadOnly(true);
textField.setLabel("Read-only");
textField.setValue("Value");
add(textField);

Set a field as read-only when the content needs to be accessible but not editable. Read-only elements cannot be edited, but they are in the tabbing order and can thus receive focus. The contents of a read-only input can be selected and copied.

Disabled

Open in a
new tab

TextField textField = new TextField();
textField.setEnabled(false);
textField.setLabel("Disabled");
textField.setValue("Value");
add(textField);

Disable a field to mark it as unavailable. The disabled state is used for fields that are not editable and do not need to be readable. Disabled elements cannot be focused and may be inaccessible to assistive technologies like screen readers.

Disabling can be preferable to hiding an element to prevent changes in layout when the element’s visibility changes, and to make users aware of its existence even when currently unavailable.

If the user needs to be able to read (or copy) the value, use read-only instead.

Focus

Focus styles are used to highlight the active element, which is useful for keyboard navigation.

Open in a
new tab

import { customElement, html, LitElement } from 'lit-element';
import '@vaadin/vaadin-form-layout';
import '@vaadin/vaadin-text-field/vaadin-password-field';
import '@vaadin/vaadin-text-field';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('input-field-focus')
export class Example extends LitElement {
    protected createRenderRoot() {
        const root = super.createRenderRoot();
        // Apply custom theme (only supported if your app uses one)
        applyTheme(root);
        return root;
    }

    steps = [
        { minWidth: '0', columns: 1 },
        { minWidth: '30em', columns: 2 },
    ];

    render() {
        return html`
      <vaadin-form-layout .responsiveSteps="${this.steps}">
        <!-- tag::snippet[] -->
        <vaadin-text-field label="First name"></vaadin-text-field>
        <vaadin-text-field label="Last name"></vaadin-text-field>
        <vaadin-text-field label="Username" colspan="2"></vaadin-text-field>
        <vaadin-password-field label="Password"></vaadin-password-field>
        <vaadin-password-field label="Confirm password"></vaadin-password-field>
        <!-- end::snippet[] -->
      </vaadin-form-layout>
    `;
    }
}

Please note that the focus style is different for keyboards and pointing devices:

Open in a
new tab

import { customElement, html, LitElement } from 'lit-element';
import '@vaadin/vaadin-ordered-layout/vaadin-horizontal-layout';
import '@vaadin/vaadin-text-field';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('input-field-focus-styles')
export class Example extends LitElement {
    protected createRenderRoot() {
        const root = super.createRenderRoot();
        // Apply custom theme (only supported if your app uses one)
        applyTheme(root);
        return root;
    }

    render() {
        return html`
      <vaadin-horizontal-layout theme="spacing">
        <!-- tag::snippet[] -->
        <vaadin-text-field label="Pointer focus" focused></vaadin-text-field>
        <vaadin-text-field label="Keyboard focus" focused focus-ring></vaadin-text-field>
        <!-- end::snippet[] -->
      </vaadin-horizontal-layout>
    `;
    }
}

Input Field Components

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

Component	Usage recommendations
Text Field	Basic single-line text input.
Text Area	Multi-line text input, for values that can’t be expected to fit on a single line, or when manual line breaks need to be supported.
Email Field	For email addresses.
Number Field	Numeric-only input such as counts, measures, or monetary values.
Password Field	Optionally masked password entry.
Date Picker	Date entry with keyboard or a calendar picker.
Time Picker	Selecting a time of day; resolution range from hours to milliseconds.
Date Time Picker	Combined date and time entry.
Radio Button	Select a single option from a list. Optimal accessibility, as all options are visible without any user action.
Select	Select a value from an overlay. More compact than Radio Buttons.
Combo Box	Select a value from a filterable overlay. Appropriate for large sets of options. Supports lazy loading and entry of custom values.
Checkbox	For selecting multiple options from a list, or a single binary toggle.

Component

Usage recommendations

Text Field

Basic single-line text input.

Text Area

Multi-line text input, for values that can’t be expected to fit on a single line, or when manual line breaks need to be supported.

Email Field

For email addresses.

Number Field

Numeric-only input such as counts, measures, or monetary values.

Password Field

Optionally masked password entry.