Edit this page

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

Automatically submits a form when a field changes.

Example

We have a search form like this:

<form method="GET" action="/search">
  <input type="search" name="query">
  <input type="checkbox" name="archive"> Include archived
</form>

To cause the form to automatically submit when either field is changed, call up.autosubmit():

up.autosubmit(form)

Observed events

element
required

The field or form to watch.

[options.event='input']
optional

The types of event to observe.

See which events to watch.

stringArray<string>
[options.delay=0]
optional

The number of milliseconds to wait between an observed event and running the callback.

See debouncing callbacks.

number

Render options

[options]
optional

Additional render options to use when the form is submitted.

Unpoly will parse render options from the watched form's attributes. You may pass this additional options object to supplement or override options parsed from attributes. See [up-submit] for a list of supported attributes.

Common options are documented below, but most options for up.submit() may be used.

Request

[options.url]
optional

Where to send the form data when the form is submitted.

Defaults to the form's [action] attribute.

string
[options.method='get']
optional

The HTTP method to use for the request.

Defaults to the form's [method] attribute.

The value is case-insensitive.

You can also use methods that would not be allowed on a <form> element, such as 'patch' or 'delete'. These will be wrapped in a POST request.

string
[options.params]
optional

Additional Form parameters that should be sent as the request's query string or payload.

The given value will be added to params parsed 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.

[options.headers={}]
optional

An object with additional request headers.

Unpoly will by default send a number of custom request headers. E.g. the X-Up-Target header includes the targeted CSS selector. See up.protocol for details.

[options.abort='target']
optional

Whether to abort existing requests before rendering.

See aborting requests for details and a list of options.

booleanstringFunction(request): boolean
[options.abortable=true]
optional

Whether the request may be aborted by other requests targeting the same fragments or layer.

See Aborting rules in layers.

boolean
[options.background=false]
optional

Whether this request will load in the background.

Background requests deprioritized over foreground requests. Background requests also won't emit up:network:late events and won't trigger the progress bar.

boolean
[options.lateDelay]
optional

The number of milliseconds after which this request can cause an up:network:late event and show the progress bar.

To prevent the event and progress bar, pass { lateDelay: false }.

Defaults to up.network.config.lateDelay.

numberboolean
[options.timeout]
optional

The number of milliseconds after which this request fails with a timeout.

Defaults to up.network.config.timeout.

number
[options.fail]
optional

Whether to render failed responses differently.

Failed responses will be rendered using options prefixed with fail, e.g. { failTarget }.

By default any HTTP status code other than 2xx or 304 is considered failed. Pass { fail: false } to handle any response as successful, even with a 4xx or 5xx status code.

booleanFunction(up.Response): boolean
[options.submitButton]
optional

The submit button used to submit the form.

If the submit button has a [name] and [value] attribute, it will be included in the request params.

By default, the form's first submit button will be assumed. Pass { submitButton: false } to not assume any submit button.

Elementfalse

Loading state

[options.disable]
optional

Disables form controls while the request is loading.

booleanstringElementArray
[options.placeholder]
optional

A placeholder to show within the targeted fragment while new content is loading.

Existing children of the targeted fragment will be hidden during the request. When the request ends for any reason, all changes will be reverted.

stringElementList<Node>
[options.preview]
optional

One or more previews that temporarily change the page while new content is loading.

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

stringFunction(up.Preview)Array
[options.feedback=true]
optional

Whether to set feedback classes while loading content.

boolean

Return value

A destructor function that stops auto-submitting when called.

Auto-submitting will stop automatically when the observed fields are removed from the DOM.

Function()