up.form up.watch(element, [options], callback)

JavaScript function

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

While you can also listen to a standard input event, using up.watch() comes with a number of quality of live improvements:

• The callback only runs when a value was actually changed. Multiple events resulting in the same value will only run the callback once.
• The callback's execution frequency can be debounced.
• Guarantees that only one async callback is running concurrently.

The unobtrusive variant of this is the [up-watch] attribute.

Example

The following would print to the console whenever an input field changes:

up.watch('input.query', function(value) {
  console.log('Query is now', value)
})

Callback arguments

The watch callback may accept up to three arguments that describe the observed change:

up.watch('input.query', function(value, name, options) {
  console.log('Query is now', value)
})

Here is a full description of the individual callback arguments:

When rendering from a watch callback, you should forward the options to the rendering function:

up.watch('input.query', function(value, name, options) { // mark-phrase "options"
  return up.reload('main', { ...options, params: { query: value }) // mark-phrase "options"
})

Tip

A rendering watch callback can often be replaced with [up-autosubmit].

Watching multiple fields

Instead of a single form field, you can also pass multiple fields, a <form> or any container that contains form fields. The callback will be run if any of the given fields change:

up.watch('form', function(value, name) {
  console.log('The value of %o is now %o', name, value)
})

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:

up.watch('input.query', function(value, name, options) {
  let url = '/search?query=' + escapeURIFragment(value)
  return up.render('.results', { url, ...options }) // mark-phrase "return"
})

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.

You can also return a promise by using async / await:

up.watch('input.query', async function(value, name, options) { // mark-phrase "async"
  let url = '/search?query=' + escapeURIFragment(value)
  await up.render('.results', { url, ...options }) // mark-phrase "await"
})

Batching changes

You may also pass the { batch: true } option to receive all changes since the last callback in a single object:

up.watch('form', { batch: true }, function(diff, options) {
  for (let name in diff) {
    let value = diff[name]
    console.log('The value of %o is now %o', name, value)
  }
})