Custom Field

Basic Usage
Value Type and Format
Native Input Fields
Supported Features
Size Variants

Custom Field is a component for wrapping multiple components as a single field. It has the same features as Input Fields, such as its label, helper, validation, and data binding. Use it to create custom input components.

Open in a
new tab

Source code

custom-field-basic.tsimport { html, LitElement } from 'lit';
import { customElement, query } from 'lit/decorators.js';
import '@vaadin/custom-field';
import '@vaadin/date-picker';
import { applyTheme } from 'Frontend/generated/theme';
import { Binder, field } from '@hilla/form';
import AppointmentModel from 'Frontend/generated/com/vaadin/demo/domain/AppointmentModel';
import { differenceInDays, parseISO, isAfter } from 'date-fns';
import type { DatePicker } from '@vaadin/date-picker';

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

  @query('#start')
  private start!: DatePicker;

  @query('#end')
  private end!: DatePicker;

  private binder = new Binder(this, AppointmentModel);

  protected override firstUpdated() {
    // Set title for screen readers
    this.start.focusElement!.setAttribute('title', 'Start date');
    this.end.focusElement!.setAttribute('title', 'End date');

    this.binder.for(this.binder.model.enrollmentPeriod).addValidator({
      message: 'Dates cannot be more than 30 days apart',
      validate: (enrollmentPeriod: string) => {
        const [from, to] = enrollmentPeriod.split('\t');

        if (from === '' || to === '') {
          return true;
        }

        return differenceInDays(parseISO(to), parseISO(from)) <= 30;
      },
    });
    this.binder.for(this.binder.model.enrollmentPeriod).addValidator({
      message: 'Start date must be earlier than end date',
      validate: (enrollmentPeriod: string) => {
        const [from, to] = enrollmentPeriod.split('\t');

        if (from === '' || to === '') {
          return true;
        }

        return isAfter(parseISO(to), parseISO(from));
      },
    });
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-custom-field
        label="Enrollment period"
        helper-text="Cannot be longer than 30 days"
        required
        ${field(this.binder.model.enrollmentPeriod)}
      >
        <vaadin-date-picker id="start" placeholder="Start date"></vaadin-date-picker>
        &ndash;
        <vaadin-date-picker id="end" placeholder="End date"></vaadin-date-picker>
      </vaadin-custom-field>
      <!-- end::snippet[] -->
    `;
  }
}
DateRangePicker.javapackage com.vaadin.demo.component.customfield;

import com.vaadin.flow.component.Text;
import com.vaadin.flow.component.customfield.CustomField;
import com.vaadin.flow.component.datepicker.DatePicker;

// tag::snippet[]
public class DateRangePicker extends CustomField<LocalDateRange> {

    private DatePicker start;
    private DatePicker end;

    public DateRangePicker(String label) {
        this();
        setLabel(label);
    }

    public DateRangePicker() {
        start = new DatePicker();
        start.setPlaceholder("Start date");
        // Sets title for screen readers
        start.getElement().executeJs(
                "this.focusElement.setAttribute('title', 'Start date')");

        end = new DatePicker();
        end.setPlaceholder("End date");
        end.getElement().executeJs(
                "this.focusElement.setAttribute('title', 'End date')");

        add(start, new Text(" – "), end);
    }

    @Override
    protected LocalDateRange generateModelValue() {
        return new LocalDateRange(start.getValue(), end.getValue());
    }

    @Override
    protected void setPresentationValue(LocalDateRange dateRange) {
        start.setValue(dateRange.getStartDate());
        end.setValue(dateRange.getEndDate());
    }
}
// end::snippet[]
CustomFieldBasic.javapackage com.vaadin.demo.component.customfield;

import com.vaadin.demo.domain.Appointment;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.data.binder.Binder;
import com.vaadin.flow.router.Route;

import java.time.temporal.ChronoUnit;

@Route("custom-field-basic")
public class CustomFieldBasic extends Div {

    public CustomFieldBasic() {
        // tag::snippet[]
        DateRangePicker dateRangePicker = new DateRangePicker();
        dateRangePicker.setLabel("Enrollment period");
        dateRangePicker.setHelperText("Cannot be longer than 30 days");
        add(dateRangePicker);

        Binder<Appointment> binder = new Binder();
        binder.forField(dateRangePicker)
                .asRequired("Enter a start and end date")
                .withValidator(
                        localDateRange -> localDateRange.getStartDate() == null
                                || localDateRange.getEndDate() == null
                                || ChronoUnit.DAYS.between(
                                        localDateRange.getStartDate(),
                                        localDateRange.getEndDate()) <= 30,
                        "Dates cannot be more than 30 days apart")
                .withValidator(
                        localDateRange -> localDateRange.getStartDate() == null
                                || localDateRange.getEndDate() == null
                                || localDateRange.getStartDate()
                                        .isBefore(localDateRange.getEndDate()),
                        "Start date must be earlier than end date")
                .bind(appointment -> new LocalDateRange(
                        appointment.getStartDate(), appointment.getEndDate()),
                        (appointment, localDateRange) -> {
                            appointment.setStartDate(
                                    localDateRange.getStartDate());
                            appointment.setEndDate(localDateRange.getEndDate());
                        });
        // end::snippet[]
    }

}
LocalDateRange.javapackage com.vaadin.demo.component.customfield;

import java.time.LocalDate;

// tag::snippet[]
public class LocalDateRange {

    private LocalDate startDate;
    private LocalDate endDate;

    public LocalDateRange(LocalDate startDate, LocalDate endDate) {
        this.startDate = startDate;
        this.endDate = endDate;
    }

    public LocalDate getStartDate() {
        return startDate;
    }

    public void setStartDate(LocalDate startDate) {
        this.startDate = startDate;
    }

    public LocalDate getEndDate() {
        return endDate;
    }

    public void setEndDate(LocalDate endDate) {
        this.endDate = endDate;
    }
}
// end::snippet[]
Appointment.javapackage com.vaadin.demo.domain;

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;


// tag::snippet[]
public class Appointment {

    private LocalTime startTime;

    private LocalDateTime startDateTime;

    private LocalDate startDate;

    private LocalTime endTime;

    private LocalDateTime endDateTime;

    private LocalDate endDate;

    private String enrollmentPeriod;

    private Integer id;

    public LocalTime getStartTime() {
        return startTime;
    }

    public void setStartTime(LocalTime startTime) {
        this.startTime = startTime;
    }

    public LocalDateTime getStartDateTime() {
        return startDateTime;
    }

    public void setStartDateTime(LocalDateTime startDateTime) {
        this.startDateTime = startDateTime;
    }

    public LocalDate getStartDate() {
        return startDate;
    }

    public void setStartDate(LocalDate startDate) {
        this.startDate = startDate;
    }

    public LocalTime getEndTime() {
        return endTime;
    }

    public void setEndTime(LocalTime endTime) {
        this.endTime = endTime;
    }

    public LocalDateTime getEndDateTime() {
        return endDateTime;
    }

    public void setEndDateTime(LocalDateTime endDateTime) {
        this.endDateTime = endDateTime;
    }

    public LocalDate getEndDate() {
        return endDate;
    }

    public void setEndDate(LocalDate endDate) {
        this.endDate = endDate;
    }

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    @Override
    public int hashCode() {
        return id;
    }

    @Override
    public boolean equals(Object obj) {
        if (this == obj) {
            return true;
        }
        if (!(obj instanceof Appointment)) {
            return false;
        }
        Appointment other = (Appointment) obj;
        return id == other.id;
    }

    public String getEnrollmentPeriod() {
        return enrollmentPeriod;
    }

    public void setEnrollmentPeriod(String enrollmentPeriod) {
        this.enrollmentPeriod = enrollmentPeriod;
    }
}
// end::snippet[]

Basic Usage

Custom Field is optimized for wrapping the following components:

It can also be used to give a label, helper, and other field features for components that don’t have them built-in, such as List Box.

Value Type and Format

Custom Field handles the value types and formats differently in Java and TypeScript.

Java

Custom Field is a generic class that requires a value type. The value type can be anything: String, List, a bean, and so forth.

Implement the generateModelValue and setPresentationValue methods to define how to build the Custom Field value from the child component values and how to propagate the Custom Field value to the child components respectively.

The following example shows how to set up value propagation, using a bean as the value type:

Source code

Javaclass Phone {
    private final String code;
    private final String number;

    public Phone(String code, String number) {
        this.code = code;
        this.number = number;
    }

    public String getCode() {
        return code;
    }

    public String getNumber() {
        return number;
    }
}

class PhoneField extends CustomField<Phone> {
    private final Select code = new Select();
    private final TextField number = new TextField();

    public PhoneField() {
        ...

        add(code, number);
    }

    @Override
    protected String generateModelValue() {
        return new Phone(code.getValue(), number.getValue());
    }

    @Override
    protected void setPresentationValue(Phone value) {
        code.setValue(value.getCode());
        number.setValue(value.getNumber());
    }
}

TypeScript

Custom Field only supports string values. The default value format is a string concatenation of the child component values, separated by the \t character.

You can customize the value format by defining your own value formatter and parser, as shown in the following example:

Source code

TypeScriptrender() {
  return html`
    <!-- Phone Custom Field -->
    <vaadin-custom-field
      .formatValue="${([code, number]: unknown[]) => {
        return code && number ? [code, number].join('|') : '';
      }}"
      .parseValue="${(value: string) => {
        return value ? value.split('|') : ['', ''];
      }}"
    >
      <!-- Country code -->
      <vaadin-select></vaadin-select>

      <!-- Phone number -->
      <vaadin-text-field></vaadin-text-field>
    </vaadin-custom-field>
  `
}

Native Input Fields

Custom Field works with native HTML elements.

The whitespace variant can be used when components without an outer margin are used within Custom Field to compensate for the missing space between the label and the component itself.

Open in a
new tab

Source code

custom-field-native-input.tsimport { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/custom-field';
import type { CustomFieldChangeEvent } from '@vaadin/custom-field';
import '@vaadin/horizontal-layout';
import { applyTheme } from 'Frontend/generated/theme';

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

  @state()
  private customFieldValue = '';

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-custom-field
        label="Payment information"
        theme="whitespace"
        @change="${(event: CustomFieldChangeEvent) => {
          this.customFieldValue = event.target.value ?? '';
        }}"
      >
        <vaadin-horizontal-layout theme="spacing-s">
          <input
            aria-label="Cardholder name"
            pattern="[\\p{L} \\-]+"
            placeholder="Cardholder name"
            required
            type="text"
          />
          <input
            aria-label="Card number"
            pattern="[\\d ]{12,23}"
            placeholder="Card number"
            required
            type="text"
          />
          <input
            aria-label="Security code"
            pattern="[0-9]{3,4}"
            placeholder="Security code"
            required
            type="text"
          />
        </vaadin-horizontal-layout>
      </vaadin-custom-field>
      <p><b>Payment information:</b> ${this.customFieldValue}</p>
      <!-- end::snippet[] -->
    `;
  }
}
PaymentInformationField.javapackage com.vaadin.demo.component.customfield;

import com.vaadin.flow.component.customfield.CustomField;
import com.vaadin.flow.component.customfield.CustomFieldVariant;
import com.vaadin.flow.component.html.Input;
import com.vaadin.flow.component.orderedlayout.HorizontalLayout;

// tag::snippet[]
public class PaymentInformationField extends CustomField<PaymentInformation> {

    private Input cardholderName;
    private Input cardNumber;
    private Input securityCode;

    public PaymentInformationField(String label) {
        this();
        setLabel(label);
    }

    public PaymentInformationField() {
        cardholderName = createInput("Cardholder name", "[\\p{L} \\-]+");
        cardNumber = createInput("Card number", "[\\d ]{12,23}");
        securityCode = createInput("Security code", "[0-9]{3,4}");

        HorizontalLayout layout = new HorizontalLayout(cardholderName,
                cardNumber, securityCode);
        // Removes default spacing
        layout.setSpacing(false);
        // Adds small amount of space between the components
        layout.getThemeList().add("spacing-s");

        // Increases padding of field's label
        addThemeVariants(CustomFieldVariant.LUMO_WHITESPACE);

        add(layout);
    }

    private Input createInput(String label, String pattern) {
        Input input = new Input();
        input.getElement().setAttribute("aria-label", label);
        input.getElement().setAttribute("pattern", pattern);
        input.getElement().setAttribute("required", true);
        input.setPlaceholder(label);
        input.setType("text");
        return input;
    }

    @Override
    protected PaymentInformation generateModelValue() {
        return new PaymentInformation(cardholderName.getValue(),
                cardNumber.getValue(), securityCode.getValue());
    }

    @Override
    protected void setPresentationValue(PaymentInformation paymentInformation) {
        cardholderName.setValue(paymentInformation.getCardholderName());
        cardNumber.setValue(paymentInformation.getCardNumber());
        securityCode.setValue(paymentInformation.getSecurityCode());
    }
}
// end::snippet[]
CustomFieldNativeInput.javapackage com.vaadin.demo.component.customfield;

import com.vaadin.flow.component.Html;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Paragraph;
import com.vaadin.flow.component.html.Span;
import com.vaadin.flow.router.Route;

@Route("custom-field-native-input")
public class CustomFieldNativeInput extends Div {

    private Span value;

    public CustomFieldNativeInput() {
        // tag::snippet[]
        PaymentInformationField paymentInformationField = new PaymentInformationField(
                "Payment information");
        paymentInformationField.addValueChangeListener(event -> {
            value.setText(event.getValue().getCardholderName() + " "
                    + event.getValue().getCardNumber() + " "
                    + event.getValue().getSecurityCode());
        });

        value = new Span();
        Paragraph paragraph = new Paragraph(
                new Html("<span><b>Payment information:</b> </span>"), value);

        add(paymentInformationField, paragraph);
        // end::snippet[]
    }

}
PaymentInformation.javapackage com.vaadin.demo.component.customfield;

// tag::snippet[]
public class PaymentInformation {

    private String cardholderName;
    private String cardNumber;
    private String securityCode;

    public PaymentInformation(String cardholderName, String cardNumber,
            String securityCode) {
        this.cardholderName = cardholderName;
        this.cardNumber = cardNumber;
        this.securityCode = securityCode;
    }

    public String getCardholderName() {
        return cardholderName;
    }

    public void setCardholderName(String cardholderName) {
        this.cardholderName = cardholderName;
    }

    public String getCardNumber() {
        return cardNumber;
    }

    public void setCardNumber(String cardNumber) {
        this.cardNumber = cardNumber;
    }

    public String getSecurityCode() {
        return securityCode;
    }

    public void setSecurityCode(String securityCode) {
        this.securityCode = securityCode;
    }
}
// end::snippet[]

Supported Features

Size Variants

The small theme variant can be used to make Custom Field’s label, helper, and error message smaller. Custom Field doesn’t propagate its theme variant to its internal components, meaning each internal component’s theme variant must be set individually.

Open in a
new tab

Source code

custom-field-size-variants.tsimport { html, LitElement } from 'lit';
import { customElement, query, state } from 'lit/decorators.js';
import '@vaadin/custom-field';
import '@vaadin/horizontal-layout';
import '@vaadin/select';
import '@vaadin/text-field';
import { applyTheme } from 'Frontend/generated/theme';
import type { Select } from '@vaadin/select';
import type { TextField } from '@vaadin/text-field';

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

  @query('#amount')
  private amount!: TextField;

  @query('#currency')
  private currency!: Select;

  @state()
  private currencies = [
    { label: 'AUD', value: 'aud' },
    { label: 'CAD', value: 'cad' },
    { label: 'CHF', value: 'chf' },
    { label: 'EUR', value: 'eur' },
    { label: 'GBP', value: 'gbp' },
    { label: 'JPY', value: 'jpy' },
    { label: 'USD', value: 'usd' },
  ];

  protected override firstUpdated() {
    // Set title for screen readers
    this.amount.focusElement!.setAttribute('title', 'Amount');
    this.currency.focusElement!.setAttribute('title', 'Currency');
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-custom-field label="Price" theme="small">
        <vaadin-horizontal-layout theme="spacing-s">
          <vaadin-text-field id="amount" theme="small"></vaadin-text-field>
          <vaadin-select
            id="currency"
            .items="${this.currencies}"
            theme="small"
            style="width: 6em;"
          ></vaadin-select>
        </vaadin-horizontal-layout>
      </vaadin-custom-field>
      <!-- end::snippet[] -->
    `;
  }
}
MoneyField.javapackage com.vaadin.demo.component.customfield;

import com.vaadin.flow.component.customfield.CustomField;
import com.vaadin.flow.component.customfield.CustomFieldVariant;
import com.vaadin.flow.component.orderedlayout.HorizontalLayout;
import com.vaadin.flow.component.select.Select;
import com.vaadin.flow.component.select.SelectVariant;
import com.vaadin.flow.component.textfield.TextField;
import com.vaadin.flow.component.textfield.TextFieldVariant;

// tag::snippet[]
public class MoneyField extends CustomField<Money> {

    private TextField amount;
    private Select<String> currency;

    public MoneyField(String label) {
        this();
        setLabel(label);
    }

    public MoneyField() {
        amount = new TextField();
        // Sets title for screen readers
        amount.getElement()
                .executeJs("this.focusElement.setAttribute('title', 'Amount')");

        currency = new Select<>();
        currency.setItems("AUD", "CAD", "CHF", "EUR", "GBP", "JPY", "USD");
        currency.setWidth("6em");
        currency.getElement().executeJs(
                "this.focusElement.setAttribute('title', 'Currency')");

        HorizontalLayout layout = new HorizontalLayout(amount, currency);
        // Removes default spacing
        layout.setSpacing(false);
        // Adds small amount of space between the components
        layout.getThemeList().add("spacing-s");

        add(layout);
    }

    public void addThemeVariant(CustomFieldVariant variant) {
        super.addThemeVariants(variant);
        amount.addThemeVariants(TextFieldVariant.valueOf(variant.name()));
        currency.addThemeVariants(SelectVariant.valueOf(variant.name()));
    }

    @Override
    protected Money generateModelValue() {
        return new Money(amount.getValue(), currency.getValue());
    }

    @Override
    protected void setPresentationValue(Money money) {
        amount.setValue(money.getAmount());
        currency.setValue(money.getCurrency());
    }
}
// end::snippet[]
CustomFieldSizeVariants.javapackage com.vaadin.demo.component.customfield;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;
import com.vaadin.flow.component.customfield.CustomFieldVariant;

@Route("custom-field-size-variants")
public class CustomFieldSizeVariants extends Div {

    public CustomFieldSizeVariants() {
        // tag::snippet[]
        MoneyField moneyField = new MoneyField("Price");
        moneyField.addThemeVariant(CustomFieldVariant.LUMO_SMALL);
        // end::snippet[]
        add(moneyField);
    }

}
Money.javapackage com.vaadin.demo.component.customfield;

// tag::snippet[]
public class Money {

    private String amount;
    private String currency;

    public Money(String amount, String currency) {
        this.amount = amount;
        this.currency = currency;
    }

    public String getAmount() {
        return amount;
    }

    public void setAmount(String amount) {
        this.amount = amount;
    }

    public String getCurrency() {
        return currency;
    }

    public void setCurrency(String currency) {
        this.currency = currency;
    }
}
// end::snippet[]

CB7FDF39-7653-4DF0-A0C0-9C2A2EE7EDBA

Documentation

Documentation

Custom Field

Basic Usage

Value Type and Format

Java

TypeScript

Native Input Fields

Supported Features

Size Variants