Custom Field

Use Custom Field for wrapping multiple components as a single field.

Usage
Styling

Basic Usage
Value Type & Format
Native Input Fields
Size Variants

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
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.setAriaLabel("Start date");

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

        // Enable manual validation on both date pickers to
        // be able to override their invalid state
        start.setManualValidation(true);
        end.setManualValidation(true);

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

    @Override
    public void setInvalid(boolean invalid) {
        super.setInvalid(invalid);
        // Propagate invalid state to both date pickers so
        // that they show a red background
        start.setInvalid(invalid);
        end.setInvalid(invalid);
    }
}

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

The type, format, and further propagation of the Custom Field value are handled differently in Java, and in Lit and React. The following two sections explain how you might configure these aspects depending on the programming language or approach you prefer.

Java

Custom Field is a generic class that accepts a value type. The value type can be anything: String, List, a bean, or something else.

When the type is specified, you need to establish how the Custom Field’s value should propagate to the child components and vice versa. The value propagation heavily depends on the Custom Field’s structure, contained components, and their types. For this reason, no default implementation is provided. Instead, Custom Field provides two methods that should be implemented manually: generateModelValue; and setPresentationValue.

The generateModelValue method defines how to generate a Custom Field value from the child components values. Custom Field triggers this method to update its value when a child component emits a change DOM event on the client-side. In this method, you typically need to collect values from all child components and return a single value of the Custom Field type based on those values.

The setPresentationValue method receives a Custom Field value and defines how to distribute it to the child components. Custom Field triggers this method to update child component values when its value changes programmatically on the server-side. In this method, you typically need to split the given value into parts and apply them to each individual child component, 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 Phone generateModelValue() {
        return new Phone(code.getValue(), number.getValue());
    }

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

Lit & React

Custom Field supports only string values. However, it does provide control over the format of the value with a parser and formatter. The parser and formatter define how Custom Field’s value should be split to child component values and vice versa. When a child component emits a change event or the Custom Field’s value changes programmatically, Custom Field propagates values based on the result of the parser or formatter.

Parser

When Custom Field’s value changes programmatically, Custom Field passes this value to the parser. The parser is supposed to convert this value into an array of child values, arranged in the order their components appear in the DOM. Custom Field then assigns these values to the child components using their value property.

The default parser returns an array of child component values, splitting the value by the \t character.

Formatter

When Custom Field detects a change event from a child component, it collects the value properties from all child components and passes them as an array to the formatter. The array contains child values in the order their components appear in the DOM. The formatter is supposed to transform this array into a single string value. The Custom Field then updates its value based on the string returned by the formatter.

The default formatter returns a 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:

function Example() {
  return (
    // Phone Custom Field
    <CustomField
      formatValue={([code, number]: unknown[]) => (code && number ? [code, number].join('|') : '')}
      parseValue={(value: string) => (value ? value.split('|') : ['', ''])}
    >
      {/* Country code */}
      <Select />

      {/* Phone number */}
      <TextField />
    </CustomField>
  );
}

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

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. Each internal component’s theme variant must be set individually.

Open in a
new tab
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.setAriaLabel("Amount");

        currency = new Select<>();
        currency.setItems("AUD", "CAD", "CHF", "EUR", "GBP", "JPY", "USD");
        currency.setWidth("6em");
        currency.setAriaLabel("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());
    }
}

CB7FDF39-7653-4DF0-A0C0-9C2A2EE7EDBA

Docs