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

# up.autosubmit(element, [options])

Automatically submits a form when a field changes.

<nav aria-label="Contents">

#### Contents

- [Example](#example)
- [Parameters](#parameters)
- [Return value](#return-value)

</nav>

## Example {#example}

We have a search form like this:

```html
<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()`:

```js
up.autosubmit(form)
```

---

## Parameters {#parameters}

### Observed events {#parameters-observed-events}

#### element {#element}

(required)

The field or form to watch.

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

#### [options.event='input'] {#options.event}

(optional)

The types of event to observe.

See [which events to watch](https://unpoly.com/learn/watch-options.md#events).

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

#### [options.delay=0] {#options.delay}

(optional)

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

See [debouncing callbacks](https://unpoly.com/learn/watch-options.md#debouncing).

Type: number

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

#### [options] {#options}

(optional)

Additional [render options](https://unpoly.com/api/up.render.md#parameters) 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](https://unpoly.com/learn/attributes-and-options.md#options) options parsed from attributes. See [`[up-submit]`](https://unpoly.com/api/up-submit.md) for a list of supported attributes.

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

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

### Request {#parameters-request}

#### [options.url] {#options.url}

(optional)

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

Defaults to the form's `[action]` attribute.

Type: string

#### [options.method='get'] {#options.method}

(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](https://unpoly.com/api/up.network.config.md#config.wrapMethod).

Type: string

#### [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)

#### [options.abort='target'] {#options.abort}

(optional)

Whether to abort existing requests before rendering.

See [aborting requests](https://unpoly.com/learn/aborting-requests.md) for details and a list of options.

Type: boolean | string | Function(request): boolean

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

(optional)

Whether the request may be aborted by other requests [targeting](https://unpoly.com/learn/targeting-fragments.md) the same fragments or layer.

See [Aborting rules in layers](https://unpoly.com/learn/aborting-requests.md#layers).

Type: boolean

#### [options.background=false] {#options.background}

(optional)

Whether this request will load in the background.

Background requests are deprioritized and won't show the [progress bar](https://unpoly.com/learn/progress-bar.md). See [Background requests](https://unpoly.com/learn/background-requests.md).

Type: boolean

#### [options.lateDelay] {#options.lateDelay}

(optional)

The number of milliseconds after which this request can cause an [`up:network:late`](https://unpoly.com/api/up:network:late.md) event and show the [progress bar](https://unpoly.com/learn/progress-bar.md).

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

Defaults to [`up.network.config.lateDelay`](https://unpoly.com/api/up.network.config.md#config.lateDelay).

Type: number | boolean

#### [options.timeout] {#options.timeout}

(optional)

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

Defaults to [`up.network.config.timeout`](https://unpoly.com/api/up.network.config.md#config.timeout).

Type: number

#### [options.fail] {#options.fail}

(optional)

Whether to render [error responses](https://unpoly.com/learn/error-responses.md) differently.

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

By [default](https://unpoly.com/api/up.network.config.md#config.fail) any HTTP status code other than 2xx or 304 is considered an error response. Pass `{ fail: false }` to handle _any_ response as successful, even with a 4xx or 5xx status code.

Type: boolean | Function([up.Response](https://unpoly.com/api/up.Response.md)): boolean

#### [options.submitButton] {#options.submitButton}

(optional)

The submit button used to submit the form. The button must belong to the form, or an error is thrown.

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.

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

### 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.

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 destructor function that stops auto-submitting when called.

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

Type: Function()