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

# up.form.config

Sets default options for form submission and validation.

---

## Value {#value}

### Submittable forms {#value-submittable-forms}

#### [config.submitSelectors] {#config.submitSelectors}

(optional)

An array of CSS selectors matching forms that will be [submitted through Unpoly](https://unpoly.com/learn/submitting-forms.md).

You can configure Unpoly to handle _all_ forms on a page without requiring an [`[up-submit]`](https://unpoly.com/api/up-submit.md) attribute:

```js
up.form.config.submitSelectors.push('form')
```

Individual forms may opt out with an `[up-submit=false]` attribute. You may configure additional exceptions in `config.noSubmitSelectors`.

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

#### [config.noSubmitSelectors] {#config.noSubmitSelectors}

(optional)

Exceptions to `up.form.config.submitSelectors`.

Matching forms will _not_ be [submitted through Unpoly](https://unpoly.com/learn/submitting-forms.md), even if they match `up.form.config.submitSelectors`.

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

### Form elements {#value-form-elements}

#### [config.groupSelectors=['[up-form-group]', 'fieldset', 'label', 'form']] {#config.groupSelectors}

(optional)

An array of CSS selectors matching a [form group](https://unpoly.com/api/up-form-group.md).

When [validating](https://unpoly.com/learn/validation.md#validating-after-changing-a-field) a field, Unpoly will re-render the [closest](https://developer.mozilla.org/en-US/docs/Web/API/Element/closest) form group around that field.

When a group is matched, Unpoly will [derive a target selector](https://unpoly.com/learn/target-derivation.md) for the element. In the example below, changing the _City_ field would validate the target `#city_group`:

```html
<fieldset id="city_group">
  <label for="city">City</label>
  <input type="text" name="city" id="city" up-validate>
</fieldset>
```

If no good selector can be derived from the group element, the resulting target will use a `:has()` suffix that matches the changed field. In the example below the target would be `fieldset:has(#city)`:

```html
<fieldset> <!-- no [id] attribute to derive a selector from -->
  <label for="city">City</label>
  <input type="text" name="city" id="city" up-validate>
</fieldset>
```

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

#### [config.fieldSelectors] {#config.fieldSelectors}

(optional)

An array of CSS selectors that represent form fields, such as `input` or `select`.

[Form-associated custom elements](https://unpoly.com/learn/custom-form-fields.md#form-associated) are matched by default and need not be added.

Add a selector to [register any element as a field](https://unpoly.com/learn/custom-form-fields.md#registering). Matching elements must have a `value` property.

You may configure exceptions in `config.noFieldSelectors`.

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

#### [config.noFieldSelectors] (Experimental) {#config.noFieldSelectors}

(optional)

Exceptions to `up.form.config.fieldSelectors`.

Matching elements will _not_ be considered a form field, even if they match `up.form.config.fieldSelectors`.

For example, a form-associated custom element that renders a button should not count as a field:

```js
up.form.config.noFieldSelectors.push('my-submit-button')
```

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

#### [config.submitButtonSelectors] {#config.submitButtonSelectors}

(optional)

An array of CSS selectors that represent submit buttons, such as `input[type=submit]` or `button[type=submit]`.

Selectors must only match native submit buttons: a `<button>` without a `[type]` or with `[type=submit]`, an `<input type="submit">` or an `<input type="image">`. A browser cannot submit a form through other elements, and [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData) rejects them.

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

#### [config.anyButtonSelectors] (Experimental) {#config.anyButtonSelectors}

(optional)

An array of CSS selectors that represent buttons of any kind, such as `button` or `input[type=button]`.

Unpoly uses this to disable a form's buttons while the form is submitting. To find the button that _submits_ a form, see `config.submitButtonSelectors`.

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

#### [config.arrayParam] (Experimental) {#config.arrayParam}

(optional)

Whether a param name is treated as an array with multiple values.

By default, only field names ending in `"[]"` are treated as arrays. You can configure another function that accepts a param name and returns a `boolean`.

If set to `true` then all fields are handled as arrays and functions like [`up.watch()`](https://unpoly.com/api/up.watch.md) always get the value passed as an array.

Type: Function(string): boolean | boolean

### Watching fields {#value-watching-fields}

#### [config.watchInputDelay=0] {#config.watchInputDelay}

(optional)

The number of milliseconds to [wait before running a watcher callback](https://unpoly.com/learn/watch-options.md#debouncing).

This default delay is only applied when [watching the `input` event](https://unpoly.com/learn/watch-options.md#events). There is no default delay when watching other types of events.

Type: number

#### [config.watchInputEvents=['input', 'change']] {#config.watchInputEvents}

(optional)

An array of events to substitute if [watching the `input` event](https://unpoly.com/learn/watch-options.md#events).

This can be used to watch [misbehaving fields](https://unpoly.com/learn/watch-options.md#normalizing-non-standard-events) that don't emit the [standard `input` event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) as its value is being edited.

It's OK to name multiple events that may result in the same change (e.g. `['keydown', 'keyup']`). Unpoly guarantees the callback is only run once per changed value.

Instead of configuring an array of event types, you may also set a function that accepts a form field and returns an array of event types to watch for that field.

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

#### [config.watchChangeEvents=['change']] {#config.watchChangeEvents}

(optional)

An array of events to substitute if [watching the `change` event](https://unpoly.com/learn/watch-options.md#events).

This can be used to watch [misbehaving fields](https://unpoly.com/learn/watch-options.md#normalizing-non-standard-events) that don't emit the [standard `change` event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) after its value was changed.

It's OK to name multiple events that may result in the same change (e.g. `['change', 'blur']`). Unpoly guarantees the callback is only run once per changed value.

Instead of configuring an array of event types, you may also set a function that accepts a form field and returns an array of event types to watch for that field.

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

### Validation {#value-validation}

#### [config.validateBatch=true] {#config.validateBatch}

(optional)

Whether to [batch validations](https://unpoly.com/api/up.validate.md#batching).

Type: boolean