Edit this page

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

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

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. Their updates will be batched together to prevent race conditions.

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 prevent race conditions, 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')

Also see preventing race conditions.


Parameters

element stringorElementorjQuery

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

See controlling what is updated.

[options.target=element] string optional

The target selector to render.

By default the given element will be rendered. If element is a field, its form group or [up-validate] target will be rendered.

[options.formGroup=true] stringorElementorjQuery optional

Whether, when a field is given as element, the field's closest form group should be targeted.

[options.origin=element] Element 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 request header.

[options.event='change'] stringorArray<string> optional

The event types to observe.

See which events to watch.

[options.delay] stringorElementorjQuery optional

The number of miliseconds to wait between an observed event and validating.

See debouncing callbacks.

[options.disable] stringorElementorjQuery optional

Whether to disable fields while waiting for the server response.

See disabling fields while working.

[options.feedback] stringorElementorjQuery optional

Whether to show navigation feedback while waiting for the server response.

See showing feedback while working.

[options.data] Object optional

Overrides properties from the new fragment's [up-data] with the given data object.

To assign data the validating element must have a derivable target selector.

[options.keepData] boolean optional

Preserve the reloaded fragment's data object.

Properties from the new fragment's [up-data] are overridden with the old fragment's [up-data].

[options] Object optional

Additional render options for the validation request.

Return value

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

The promise rejects when one of the following conditions occur: