Documentation

Documentation

Custom Field

Source: TypeScript / Java
Custom Field is a component for wrapping multiple components as a single field.

Custom Field is a component for wrapping multiple components as a single field. It provides standard input field features like label, helper, validation, and data binding. Use it to create custom input components.

Open in a
new tab
<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>

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 & Format

Java

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

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:

class 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:

render() {
  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
<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>

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

CB7FDF39-7653-4DF0-A0C0-9C2A2EE7EDBA