Edit this page

up.form [up-watch]
HTML selector

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

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

The programmatic variant of this is the up.watch() function.


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

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

Callback context

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

Name Type Description
this Element The changed form field
name Element The [name] of the changed field
value string The new value of the changed field

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:

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

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

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

<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">

Watching radio buttons

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

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

<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

Async callbacks

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

<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


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

[up-watch-event='input'] optional

The type of event to watch.

See which events to watch.

[up-watch-delay] optional

The number of miliseconds to wait after a change before the code is run.

See debouncing callbacks.

[up-watch-disable] optional

Whether to disable fields while an async callback is running.

See disabling fields while working.

[up-watch-feedback] optional

Whether to show navigation feedback while an async callback is running.

See showing feedback while working.