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.

Example

The following would log a message 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:

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:

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

<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

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
</div>

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:

<input name="query" up-watch="return asyncWork()"> <!-- 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.