Custom Field

Basic Usage
Native Input Fields
Supported Features
Required Field Indicator Visibility
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 own label, helper, validation, and data binding. Use it to create custom input components.

Open in a
new tab

Source code

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");

    end = new DatePicker();
    end.setPlaceholder("End date");

    // aria-label for screen readers
    start.getElement()
      .executeJs("const start = this.shadowRoot.querySelector('[part=\"text-field\"]').shadowRoot.querySelector('[part=\"value\"]');" +
        "start.setAttribute('aria-label', 'Start date');" +
        "start.removeAttribute('aria-labelledby');"
      );
    end.getElement()
      .executeJs("const end = this.shadowRoot.querySelector('[part=\"text-field\"]').shadowRoot.querySelector('[part=\"value\"]');" +
        "end.setAttribute('aria-label', 'End date');" +
        "end.removeAttribute('aria-labelledby');"
      );

    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 optimised for wrapping the following components:

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

Native Input Fields

Custom Field works with native HTML elements.

Open in a
new tab

Source code

PaymentInformationField.javapackage com.vaadin.demo.component.customfield;

import com.vaadin.flow.component.customfield.CustomField;
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");

    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

Required Field Indicator Visibility

The visibility of the required field indicator is controlled by the has-value attribute on the Custom Field component. In Flow (Java), a class extending CustomField should take care of toggling the has-value attribute based on what values are considered empty.

Size Variants

The small theme variant can be used to make Custom Field’s label, helper, and error message smaller. Custom Field does not 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

MoneyField.javapackage com.vaadin.demo.component.customfield;

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

// 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();

    currency = new Select();
    currency.setItems("AUD", "CAD", "CHF", "EUR", "GBP", "JPY", "USD");
    currency.setWidth("6em");

    // aria-label for screen readers
    amount.getElement()
      .executeJs("const amount = this.shadowRoot.querySelector('[part=\"value\"]');" +
        "amount.setAttribute('aria-label', 'Amount');" +
        "amount.removeAttribute('aria-labelledby');");
    currency.getElement()
      .executeJs("const currency = this.shadowRoot.querySelector('vaadin-select-text-field').shadowRoot.querySelector('[part=\"input-field\"]');" +
        "currency.setAttribute('aria-label', 'Currency');" +
        "currency.removeAttribute('aria-labelledby');");

    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(String theme) {
    getElement().getThemeList().add(theme);
    amount.addThemeName(theme);
    currency.getElement().getThemeList().add(theme);
  }

  @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;

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

  public CustomFieldSizeVariants() {
    // tag::snippet[]
    MoneyField moneyField = new MoneyField("Price");
    moneyField.addThemeVariant("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[]

CDC76788-C339-411B-89BF-510C3603EF59

Docs

Docs

Custom Field

Basic Usage

Native Input Fields

Supported Features

Required Field Indicator Visibility

Size Variants