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

# [up-watch]

Watches form fields and runs a callback when a value changes.

Only fields with a `[name]` attribute can be watched.

<nav aria-label="Guides">

- [Learn: Submitting forms](https://unpoly.com/learn/submitting-forms.md#autosubmit)

</nav>

<nav aria-label="Contents">

#### Contents

- [Example](#example)
- [Callback context](#callback-context)
- [Watching multiple fields](#watching-multiple-fields)
- [Watching radio buttons](#watching-radio-buttons)
- [Async callbacks](#async-callbacks)
- [Modifying attributes](#attributes)

</nav>

## Example {#example}

The following would log a message whenever the `<input>` changes:

```html
<input name="query" up-watch="console.log('New value', value)">
```

## Callback context {#callback-context}

The script given to `[up-watch]` runs with the following context:

| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | The changed field value. |
| `name` | `string` | The `[name]` of the changed field. |
| `options.origin` | [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element) | The element that caused the change. This is usually the changed field. |
| `options.feedback` | `boolean` | Whether to set [feedback classes](https://unpoly.com/learn/feedback-classes.md) while working. Parsed from the field's `[up-watch-feedback]` attribute. |
| `options.disable` | `boolean` | Which [fields to disable](https://unpoly.com/learn/disabling-forms.md) while working. Parsed from the field's `[up-watch-disable]` attribute. |
| `options.preview` | `string` | The name of a [preview](https://unpoly.com/learn/previews.md) to run while working. Parsed from the field's `[up-watch-preview]` attribute. |
| `options.placeholder` | `string` | The HTML or selector for a [placeholder](https://unpoly.com/learn/placeholders.md) to show while working. Parsed from the field's `[up-watch-placeholder]` attribute. |

## Watching multiple fields {#watching-multiple-fields}

You can set `[up-watch]` on any element to observe all contained fields. The `name` argument contains the name of the field that was changed:

```html
<form>
  <div up-watch="console.log(`New value of ${name} is ${value}`)">
    <input type="email" name="email">
    <input type="password" name="password">
  </div>

  <!-- This field is outside the [up-watch] container and will not be watched -->
  <input type="text" name="screen-name">
</form>
```

You may also set `[up-watch]` on a `<form>` element to watch _all_ fields in a form:

```html
<form up-watch="console.log(`New value of ${name} is ${value}`)">
  <input type="email" name="email">
  <input type="password" name="password">
  <input type="text" name="screen-name">
</form>
```

## Watching radio buttons {#watching-radio-buttons}

Multiple radio buttons with the same `[name]` produce a single value for the form.

To watch a group of radio buttons, use the `[up-watch]` attribute on an element that contains all radio button elements with a given name:

```html
<div up-watch="console.log('New value is', value)">
  <input type="radio" name="format" value="html"> HTML format
  <input type="radio" name="format" value="pdf"> PDF format
  <input type="radio" name="format" value="txt"> Text format
</div>
```

## Async callbacks {#async-callbacks}

When your callback does async work (like fetching data over the network), it must return a promise that settles once the work concludes:

```html
<input name="query" up-watch="return asyncWork()">
```

Unpoly will guarantee that only one async callback is running concurrently. If the form is changed while an async callback is still processing, Unpoly will wait until the callback concludes and then run it again with the latest field values.

---

## Modifying attributes {#attributes}

### Callback {#attributes-callback}

#### up-watch {#up-watch}

(required)

The code to run when any field's value changes.

See [callback context](#callback-context).

### Observed events {#attributes-observed-events}

#### [up-watch-event='input'] {#up-watch-event}

(optional)

The type of event to watch.

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

#### [up-watch-delay=0] {#up-watch-delay}

(optional)

The number of milliseconds to wait after a change.

This can be used to batch multiple events within a short time span. See [debouncing callbacks](https://unpoly.com/learn/watch-options.md#debouncing).