> Markdown version of [Form API](https://vaadin.com/docs/next/flow/react-views/forms/api). Section index: [llms.txt](https://vaadin.com/docs/next/flow/llms.txt)

# Form API

The hooks of form binding are in the `@vaadin/hilla-react-form` package. The validation types are in `@vaadin/hilla-lit-form`, and the model helpers in `@vaadin/hilla-models`.

## <a id="use-form"></a>useForm

`useForm(model, config?)` creates a form for the given model, and returns its state and functions. The optional configuration object has these properties:

- `onSubmit(value)`

  An asynchronous function that `submit()` calls with the value of the form. See [Submitting](https://vaadin.com/docs/next/flow/react-views/forms.md#submitting).

- `onChange(oldValue)`

  A function that the form calls when it updates its value, with the value before the update.

The result has the state properties described in [Form State](https://vaadin.com/docs/next/flow/react-views/forms/form-state.md#properties), and these functions:

- `field(model)`

  Returns the properties that bind a component to the field of the given model. Spread them on the component. See [Field Components](https://vaadin.com/docs/next/flow/react-views/forms/field-components.md).

- `read(value)`

  Sets the value and the default value of the form, and clears the validation errors. With `null` or `undefined`, it clears the form.

- `reset()`

  Sets the value back to the default value.

- `clear()`

  Sets the value and the default value to the default values of the model.

- `submit()`

  Validates the form, and calls `onSubmit`. Returns a promise that resolves with the result of `onSubmit`, or rejects with a `ValidationError`.

- `setValue(value)`

  Sets the value of the form.

- `setDefaultValue(value)`

  Sets the default value of the form, which affects the `dirty` state and `reset()`.

- `validate()`

  Validates the form, and returns a promise of its errors.

- `addValidator(validator)`

  Adds a validator to the form. See [Form Validators](https://vaadin.com/docs/next/flow/react-views/forms/validation.md#form-validators).

- `setValidators(validators)`

  Replaces the validators of the form.

- `setVisited(visited)`

  Sets the `visited` state.

- `update()`

  Re-renders the component.

## <a id="use-form-part"></a>useFormPart

`useFormPart(model)` returns the state and functions of a part of a form, such as a field or a nested object. The model must belong to a form that a `useForm()` call in the same or a parent component created.

The result has the state properties described in [Form State](https://vaadin.com/docs/next/flow/react-views/forms/form-state.md#properties), except `submitting`, and the `field()`, `setValue()`, `validate()`, `addValidator()`, `setValidators()`, and `setVisited()` functions of `useForm()`. They apply to the part.

The validators of a field include the validators of its Bean Validation constraints. Calling `setValidators()` replaces them, too.

## <a id="use-form-array-part"></a>useFormArrayPart

`useFormArrayPart(model)` returns the state and functions of a list or an array in a form, like `useFormPart()`, but without `field()`. Its `items` property contains a model for each item. The model must be non-nullable. See [Arrays](https://vaadin.com/docs/next/flow/react-views/forms/nested-objects-arrays.md#arrays).

## <a id="validation-types"></a>Validation Types

The `@vaadin/hilla-lit-form` package has these types for validation:

- `Validator`

  An object with a `message`, a `validate(value)` function, and an optional `impliesRequired` flag. See [Validators in the View](https://vaadin.com/docs/next/flow/react-views/forms/validation.md#validators).

- `ValueError`

  A validation error, with the `property` that identifies the field, the `message`, the `value`, and the `validator` that failed.

- `ValidationError`

  The error that `submit()` rejects with when the validation fails. Its `errors` property contains the `ValueError` objects.

- `BinderRoot`

  Its static `interpolateMessageCallback` property replaces the placeholders in the messages of constraints. See [Error Messages](https://vaadin.com/docs/next/flow/react-views/forms/validation.md#messages).

The package also has a validator class for each Bean Validation constraint that the browser checks, such as `NotBlank`, `Size`, and `Pattern`. They take an options object with a `message` and the attributes of the constraint, such as `new Size({ min: 3, max: 20 })`.

## <a id="models"></a>Form Models

A generated form model, such as `PersonModel`, is both a value and a type with the same name. Pass the value to the hooks, and use the type for the properties of components that get a part of the form.

The `$defaultValue` symbol from `@vaadin/hilla-models` gives the default value of a model, such as `PersonModel[$defaultValue]`.
