---
name: "up.validate"
area: "API"
kind: "JavaScript function"
parent: "up.form module"
url: "https://unpoly.com/api/up.validate"
---
<nav aria-label="Unpoly docs">[All docs](https://unpoly.com/index.md) · [up.form module](https://unpoly.com/api/up.form.md)</nav>

# up.validate(element, options, [options])

Renders a new form state from its current field values, to show validation errors or update [dependent elements](https://unpoly.com/learn/reactive-server-forms.md).

Typical use cases are to [show validation errors](https://unpoly.com/learn/validation.md#validating-after-changing-a-field) after a field was changed or to update forms where one field depends on the value of another.

`up.validate()` submits the given element's form with an additional [`X-Up-Validate`](https://unpoly.com/api/X-Up-Validate.md) HTTP header. Upon seeing this header, the server is expected to validate (but not commit) the form submission and render a new form state. See [this example](https://unpoly.com/api/up-validate.md#backend-protocol) for control flow on the server.

To automatically update a form after a field was changed, use the [`[up-validate]`](https://unpoly.com/api/up-validate.md) attribute. You may combine [`[up-validate]`](https://unpoly.com/api/up-validate.md) and `up.validate()` within the same form. In order to reduce requests, their updates will be [batched together](#batching).

<nav aria-label="Guides">

- [Learn: Reactive server forms](https://unpoly.com/learn/reactive-server-forms.md)

</nav>

<nav aria-label="Contents">

#### Contents

- [Controlling what is updated](#controlling-what-is-updated)
- [Multiple validations are batched together](#batching)
- [Preventing race conditions](#preventing-race-conditions)
- [Parameters](#parameters)
- [Return value](#return-value)

</nav>

## Controlling what is updated {#controlling-what-is-updated}

`up.validate()` always submits the entire form with its current field values to the form's `[action]` path. Typically only a fragment of the form is updated with the response. This minimizes the chance for loss of transient state like scroll positions, cursor selection or user input while the request is in flight.

Passing a form field will update the closest [form group](https://unpoly.com/api/up-form-group.md) around the field:

```js
up.validate('input[name=email]')
```

If the given field has an [`[up-validate]`](https://unpoly.com/api/up-validate.md) attribute with a custom target selector, that selector will be updated instead.

You may also update arbitrary elements within the form:

```js
up.validate('.preview')
```

You may also choose to re-render an entire form. In this case it is recommended to [disable fields](https://unpoly.com/learn/disabling-forms.md) while rendering. This prevents the loss of user input made while the request is in flight:

```js
up.validate('form', { disable: true })
```

## Multiple validations are batched together {#batching}

In order to reduce requests, multiple calls of `up.validate()` within the same [task](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules/) are consolidated into a single request. For instance, the following will send a single request [targeting](https://unpoly.com/learn/targeting-fragments.md) `.foo, .bar`:

```js
up.validate('.foo')
up.validate('.bar')
```

Validating the same target multiple times will also only send a single request. For instance, the following will send a single request targeting `.qux`:

```js
up.validate('.qux')
up.validate('.qux')
```

When one of your target elements is an ancestor of another target, Unpoly will only request the ancestor. For instance, the following would send a single request targeting `form`:

```js
up.validate('input[name=email]')
up.validate('form')
```

When a validation request is already in flight, additional validations are [queued](https://unpoly.com/learn/reactive-server-forms.md#race-conditions). When the current request has loaded, queued validations are batched using the same rules as outlined above.

### Batching with multiple URLs {#batching-multiple-urls}

Even with multiple URLs, only a single validation request per form will be in flight at the same time.

Batches will be partitioned by URL. Batch requests are sent in sequence, with no concurrency. Additional validations are queued until the current batch request has loaded.

For instance, let's assume the following four validations are queued:

```js
up.validate('.foo', { url: '/path1' })
up.validate('.bar', { url: '/path2' })
up.validate('.baz', { url: '/path1' })
up.validate('.qux', { url: '/path2' })
```

This will send a sequence of two requests:

1. A request to `/path1` targeting `.foo, .baz`. The other validations are queued.
2. Once that request finishes, a second request to `/path2` targeting `.bar, .qux`.

### Disabling batching {#batching-disable}

By disabling batching, Unpoly will send individual requests for each call to `up.validate()` and for each change of an [`[up-validate]`](https://unpoly.com/api/up-validate.md) field. Additional validations are queued until the current validation request has loaded.

There are multiple ways to disable batching:

- Globally by configuring `up.form.config.validateBatch = false`.
- Setting an [`[up-validate-batch]`](https://unpoly.com/api/up-validate.md) attribute on the element with [`[up-validate]`](https://unpoly.com/api/up-validate.md).
- Passing an option `up.validate(element, { batch: false })`.

## Preventing race conditions {#preventing-race-conditions}

Unpoly sends one validation request per form at a time and batches the rest.

See [preventing race conditions](https://unpoly.com/learn/reactive-server-forms.md#race-conditions) for details.

---

## Parameters {#parameters}

### Targeting {#parameters-targeting}

#### element {#element}

(required)

The field or fragment that should be re-rendered on the server.

See [controlling what is updated](#controlling-what-is-updated).

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [jQuery](https://learn.jquery.com/using-jquery-core/jquery-object/)

#### [options.target=element] {#options.target}

(optional)

The [target selector](https://unpoly.com/learn/targeting-fragments.md) to re-render.

By default, the given `element` will be rendered. If `element` is a field, its form group or [`[up-validate]`](https://unpoly.com/api/up-validate.md) target will be rendered.

Type: string

#### [options.formGroup=true] {#options.formGroup}

(optional)

Whether, when a field is given as `element`, the field's closest [form group](https://unpoly.com/api/up-form-group.md) should be targeted.

Type: boolean

#### [options.origin=element] {#options.origin}

(optional)

The element or field that caused this validation pass.

The names of all fields contained within the origin will be passed as an [`X-Up-Validate`](https://unpoly.com/api/X-Up-Validate.md) request header.

Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)

### Render options {#parameters-render-options}

#### [options] {#options}

(optional)

Additional [render options](https://unpoly.com/api/up.render.md#parameters) to use when re-rendering the targeted fragment.

Common options are documented below, but most [options for `up.submit()`](https://unpoly.com/api/up.submit.md#parameters) may be used.

Note that validation requests may be [batched together](https://unpoly.com/api/up.validate.md#batching). In this case Unpoly will try to merge render options where possible (e.g. `{ headers, target }`). When a render option cannot be merged (e.g. `{ scroll }`), the option from the last validation in the batch will be used.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

### Client state {#parameters-client-state}

#### [options.keepData] {#options.keepData}

(optional)

Whether to [preserve](https://unpoly.com/learn/data.md#preserving) the fragment's [data object](https://unpoly.com/learn/data.md) throughout the update.

Properties from the new fragment's [`[up-data]`](https://unpoly.com/api/up-data.md) are overridden with the old fragment's [`[up-data]`](https://unpoly.com/api/up-data.md).

Type: boolean

#### [options.data] {#options.data}

(optional)

The [data](https://unpoly.com/learn/data.md) object for the new fragment.

If the new fragment already has an [`[up-data]`](https://unpoly.com/api/up-data.md) object, properties from `{ data }` take precedence.

When updating [multiple fragments](https://unpoly.com/learn/targeting-fragments.md#multiple), `{ data }` is only applied to the primary fragment. To apply data to multiple fragments, use [`{ dataMap }`](#options.dataMap).

See [Overriding data for a render pass](https://unpoly.com/learn/data.md#override).

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

#### [options.dataMap] (Experimental) {#options.dataMap}

(optional)

An object mapping selectors to [data objects](https://unpoly.com/learn/data.md).

When a selector matches any element within an updated fragment, the matching element is compiled with the mapped data.

See [Mapping selectors to data](https://unpoly.com/learn/data.md#map).

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

#### [options.keep=true] (Experimental) {#options.keep}

(optional)

Whether [`[up-keep]`](https://unpoly.com/api/up-keep.md) elements will be kept in the updated fragments.

Type: boolean

#### [options.context] (Experimental) {#options.context}

(optional)

An object that will be merged into the [context](https://unpoly.com/learn/layer-context.md) of the current layer once the fragment is rendered.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

### Request {#parameters-request}

#### options.url {#options.url}

(required)

The URL to which to submit the validation request.

By default, Unpoly will use the form's `[action]` attribute.

See [Validating against other URLs](https://unpoly.com/api/up-validate.md#urls).

Type: string

#### options.method {#options.method}

(required)

The method to use for submitting the validation request.

By default, Unpoly will use the form's `[method]` attribute.

See [Validating against other URLs](https://unpoly.com/api/up-validate.md#urls).

Type: string

#### [options.batch=true] {#options.batch}

(optional)

Whether to [consolidate multiple validations into a single request](https://unpoly.com/api/up.validate.md#batching).

Defaults to [`up.form.config.validateBatch`](https://unpoly.com/api/up.form.config.md#config.validateBatch), which defaults to `true`.

Type: boolean

#### [options.params] {#options.params}

(optional)

Additional [Form parameters](https://unpoly.com/api/up.Params.md) that should be sent as the request's [query string](https://en.wikipedia.org/wiki/Query_string) or payload.

The given value will be added to params [parsed](https://unpoly.com/api/up.Params.fromForm.md) from the form's input fields. If a param with the same name already existed in the form, it will be deleted and overridden with the given value.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects) | [up.Params](https://unpoly.com/api/up.Params.md) | [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) | string | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

#### [options.headers={}] {#options.headers}

(optional)

An object with additional request headers.

Unpoly will by default send a number of custom request headers. For example, the [`X-Up-Target`](https://unpoly.com/api/X-Up-Target.md) header includes the [targeted](https://unpoly.com/learn/targeting-fragments.md) CSS selector. See [`up.protocol`](https://unpoly.com/api/up.protocol.md) for details.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

### Loading state {#parameters-loading-state}

#### [options.disable] {#options.disable}

(optional)

[Disables form controls](https://unpoly.com/learn/disabling-forms.md) while the request is loading.

The values of disabled fields will still be included in the submitted form params.

Type: boolean | string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

#### [options.placeholder] (Experimental) {#options.placeholder}

(optional)

A [placeholder](https://unpoly.com/learn/placeholders.md) to show within the targeted fragment while new content is loading.

Existing children of the targeted fragment [will be hidden](https://unpoly.com/learn/placeholders.md#basic-example) during the request. When the request ends for any reason, all changes will be reverted.

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [List](https://unpoly.com/api/List.md)<[Node](https://developer.mozilla.org/en-US/docs/Web/API/Node)>

#### [options.preview] {#options.preview}

(optional)

One or more [previews](https://unpoly.com/learn/previews.md) that temporarily change the page while new content is loading.

The preview changes will be reverted automatically when the request ends for any reason.

Type: string | Function([up.Preview](https://unpoly.com/api/up.Preview.md)) | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

#### [options.feedback=true] {#options.feedback}

(optional)

Whether to set [feedback classes](https://unpoly.com/learn/feedback-classes.md) while loading content.

Type: boolean

---

## Return value {#return-value}

A promise that fulfills when the server-side validation is received and the form was updated.

Type: [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)<[up.RenderResult](https://unpoly.com/api/up.RenderResult.md)>