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

JavaScript function

Render a new form state from its current field values, to show validation errors or update dependent elements.

Typical use cases are to show validation errors 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 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 for control flow on the server.

To automatically update a form after a field was changed, use the the [up-validate] attribute. You may combine [up-validate] and up.validate() within the same form. In order to reduce requests, their updates will be batched together.

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 around the field:

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

If the given field has an [up-validate] attribute with a custom target selector, that selector will be updated instead.

You may also update arbitrary elements within the form:

up.validate('.preview')

You may also choose to re-render an entire form. In this case it is recommended to disable fields while rendering. This prevents the loss of user input made while the request is in flight:

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

Multiple validations are batched together

In order to reduce requests, multiple calls of up.validate() within the same task are consolidated into a single request. For instance, the following will send a single request targeting .foo, .bar:

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:

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:

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

When a validation request is already in flight, additional validations are queued. When the current request has loaded, queued validations are batched using the same rules as outlined above.

Batching with 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:

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 /path targeting .foo, .baz. The other validations are queued.
2. Once that request finishes, a second request to /path2 targeting .bar, .qux.

Disabling batching

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

There are multiple ways to disable batching:

• Globally configuring up.form.config.validateBatch = true.
• Setting an [up-validate-batch] attribute on the element with [up-validate].
• Passing an option up.validate(element, { batch: false }).

Preventing race conditions

Unpoly guarantees that many concurrent validations will eventually show a consistent form state, regardless of how fast the user clicks or how slow the network is.

See preventing race conditions for details.