Nested Objects & Arrays

Bind the properties of nested objects, split a form into components, and add and remove the items of a list.

Nested Objects
Arrays

A property of a Java type can be another object, or a list of objects. The examples on this page use the Person record on Forms, which has an address and a list of phone numbers:

Source code

Address.javapackage com.vaadin.demo.fusion.forms.person;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Pattern;

public record Address(@NotBlank String street,
        @Pattern(regexp = "\\d{5}", message = "Enter five digits") String postalCode,
        @NotBlank String city) {
}

Source code

PhoneNumber.javapackage com.vaadin.demo.fusion.forms.person;

import jakarta.validation.constraints.NotBlank;

public record PhoneNumber(@NotBlank String number, String label) {
}

Keep nested objects and lists non-nullable, for example by annotating their package with @NullMarked. The useFormArrayPart() hook doesn’t accept the model of a nullable list.

Nested Objects

The model of an object property has models for the properties of the object, so a field can bind to them directly, such as field(model.address.street). The name of the field is the path of the property, address.street. The errors of the server use the same path, so that they appear in the right field.

To split a form into components, pass the model of a nested object to a component, and call useFormPart() there. The part has a field() function of its own, and the state of the nested object, as described in Form State. Type the property of the component with the generated model type, which has the same name as the model:

Source code

person-details-form.tsximport { useEffect } from 'react';
import { $defaultValue } from '@vaadin/hilla-models';
import { useForm, useFormArrayPart, useFormPart } from '@vaadin/hilla-react-form';
import { Button, HorizontalLayout, TextField, VerticalLayout } from '@vaadin/react-components';
import type AddressModel from 'Frontend/generated/com/vaadin/demo/fusion/forms/person/AddressModel';
import PersonModel from 'Frontend/generated/com/vaadin/demo/fusion/forms/person/PersonModel';
import PhoneNumberModel from 'Frontend/generated/com/vaadin/demo/fusion/forms/person/PhoneNumberModel';
import { PersonService } from 'Frontend/generated/endpoints';

function AddressForm({ model }: { model: AddressModel }) {
  const { field } = useFormPart(model);

  return (
    <HorizontalLayout theme="spacing">
      <TextField label="Street" {...field(model.street)} />
      <TextField label="Postal code" {...field(model.postalCode)} />
      <TextField label="City" {...field(model.city)} />
    </HorizontalLayout>
  );
}

function PhoneNumberForm({ model, onRemove }: { model: PhoneNumberModel; onRemove(): void }) {
  const { field } = useFormPart(model);

  return (
    <HorizontalLayout theme="spacing">
      <TextField label="Number" {...field(model.number)} />
      <TextField label="Label" {...field(model.label)} />
      <Button onClick={onRemove}>Remove</Button>
    </HorizontalLayout>
  );
}

export default function PersonDetailsView() {
  const { model, field, read } = useForm(PersonModel);
  const phoneNumbers = useFormArrayPart(model.phoneNumbers);
  const numbers = phoneNumbers.value ?? [];

  useEffect(() => {
    PersonService.loadPerson().then(read);
  }, []);

  return (
    <VerticalLayout theme="padding">
      <TextField label="First name" {...field(model.firstName)} />
      <AddressForm model={model.address} />
      {phoneNumbers.items.map((item, index) => (
        <PhoneNumberForm
          key={index}
          model={item}
          onRemove={() => phoneNumbers.setValue(numbers.filter((_, i) => i !== index))}
        />
      ))}
      <Button onClick={() => phoneNumbers.setValue([...numbers, PhoneNumberModel[$defaultValue]])}>
        Add phone number
      </Button>
    </VerticalLayout>
  );
}

Arrays

For a list or an array, call useFormArrayPart() with its model. Besides the state of the list, the result has an items property, with a model for each item. Bind the fields of each item to its model, for example in a component of their own:

Source code

person-details-form.tsximport { useEffect } from 'react';
import { $defaultValue } from '@vaadin/hilla-models';
import { useForm, useFormArrayPart, useFormPart } from '@vaadin/hilla-react-form';
import { Button, HorizontalLayout, TextField, VerticalLayout } from '@vaadin/react-components';
import type AddressModel from 'Frontend/generated/com/vaadin/demo/fusion/forms/person/AddressModel';
import PersonModel from 'Frontend/generated/com/vaadin/demo/fusion/forms/person/PersonModel';
import PhoneNumberModel from 'Frontend/generated/com/vaadin/demo/fusion/forms/person/PhoneNumberModel';
import { PersonService } from 'Frontend/generated/endpoints';

function AddressForm({ model }: { model: AddressModel }) {
  const { field } = useFormPart(model);

  return (
    <HorizontalLayout theme="spacing">
      <TextField label="Street" {...field(model.street)} />
      <TextField label="Postal code" {...field(model.postalCode)} />
      <TextField label="City" {...field(model.city)} />
    </HorizontalLayout>
  );
}

function PhoneNumberForm({ model, onRemove }: { model: PhoneNumberModel; onRemove(): void }) {
  const { field } = useFormPart(model);

  return (
    <HorizontalLayout theme="spacing">
      <TextField label="Number" {...field(model.number)} />
      <TextField label="Label" {...field(model.label)} />
      <Button onClick={onRemove}>Remove</Button>
    </HorizontalLayout>
  );
}

export default function PersonDetailsView() {
  const { model, field, read } = useForm(PersonModel);
  const phoneNumbers = useFormArrayPart(model.phoneNumbers);
  const numbers = phoneNumbers.value ?? [];

  useEffect(() => {
    PersonService.loadPerson().then(read);
  }, []);

  return (
    <VerticalLayout theme="padding">
      <TextField label="First name" {...field(model.firstName)} />
      <AddressForm model={model.address} />
      {phoneNumbers.items.map((item, index) => (
        <PhoneNumberForm
          key={index}
          model={item}
          onRemove={() => phoneNumbers.setValue(numbers.filter((_, i) => i !== index))}
        />
      ))}
      <Button onClick={() => phoneNumbers.setValue([...numbers, PhoneNumberModel[$defaultValue]])}>
        Add phone number
      </Button>
    </VerticalLayout>
  );
}

To add or remove items, call setValue() with a new list. The default value of a model, such as PhoneNumberModel[$defaultValue], is an empty item. Import $defaultValue from @vaadin/hilla-models:

Source code

person-details-form.tsximport { useEffect } from 'react';
import { $defaultValue } from '@vaadin/hilla-models';
import { useForm, useFormArrayPart, useFormPart } from '@vaadin/hilla-react-form';
import { Button, HorizontalLayout, TextField, VerticalLayout } from '@vaadin/react-components';
import type AddressModel from 'Frontend/generated/com/vaadin/demo/fusion/forms/person/AddressModel';
import PersonModel from 'Frontend/generated/com/vaadin/demo/fusion/forms/person/PersonModel';
import PhoneNumberModel from 'Frontend/generated/com/vaadin/demo/fusion/forms/person/PhoneNumberModel';
import { PersonService } from 'Frontend/generated/endpoints';

function AddressForm({ model }: { model: AddressModel }) {
  const { field } = useFormPart(model);

  return (
    <HorizontalLayout theme="spacing">
      <TextField label="Street" {...field(model.street)} />
      <TextField label="Postal code" {...field(model.postalCode)} />
      <TextField label="City" {...field(model.city)} />
    </HorizontalLayout>
  );
}

function PhoneNumberForm({ model, onRemove }: { model: PhoneNumberModel; onRemove(): void }) {
  const { field } = useFormPart(model);

  return (
    <HorizontalLayout theme="spacing">
      <TextField label="Number" {...field(model.number)} />
      <TextField label="Label" {...field(model.label)} />
      <Button onClick={onRemove}>Remove</Button>
    </HorizontalLayout>
  );
}

export default function PersonDetailsView() {
  const { model, field, read } = useForm(PersonModel);
  const phoneNumbers = useFormArrayPart(model.phoneNumbers);
  const numbers = phoneNumbers.value ?? [];

  useEffect(() => {
    PersonService.loadPerson().then(read);
  }, []);

  return (
    <VerticalLayout theme="padding">
      <TextField label="First name" {...field(model.firstName)} />
      <AddressForm model={model.address} />
      {phoneNumbers.items.map((item, index) => (
        <PhoneNumberForm
          key={index}
          model={item}
          onRemove={() => phoneNumbers.setValue(numbers.filter((_, i) => i !== index))}
        />
      ))}
      <Button onClick={() => phoneNumbers.setValue([...numbers, PhoneNumberModel[$defaultValue]])}>
        Add phone number
      </Button>
    </VerticalLayout>
  );
}

The models in items follow the positions in the list, so use the index as the key. The name of a field in an item contains the index, such as phoneNumbers.0.number.

Docs

Docs

Nested Objects & Arrays

Nested Objects

Arrays