Version 3.17.2

The valuechange Event

Jump to Table of Contents

The event-valuechange module adds a "valuechange" event that fires when the value property of an <input>, <textarea>, <select>, or [contenteditable="true"] element changes as the result of a keystroke, mouse operation, or input method editor (IME) input event.

What's the problem?

The input related events provided by browsers don't cleanly address the variety of ways users can modify an <input> or <textarea>'s value. For example, users might change an input value by:

  • typing a simple character
  • typing a multi-stroke character
  • using an Input Method Editor
  • cutting from or pasting into the value with Ctrl+X or Cmd+V
  • cutting or pasting with a keyboard-summoned context menu
  • cutting or pasting from the right-click context menu.

The ideal change event would fire when the value becomes something it wasn't a moment ago.

The valuechange event provides more reliable input notifications than native events like oninput and textInput, particularly with changes that result from multiple-keystroke IME input.

commentTextarea.on('valuechange', updateLivePreview);

How it works

valuechange subscriptions monitor the element's value using a variety of mechanisms including subscriptions to focus and various keyboard events, and a poll to catch the stragglers. It seems like a lot of work, but it's the only way to be sure.

Polling is only active when the element is focused, and only one element is polled at a time, so the performance of your app should not be impacted.

Caveats

  • valuechange only supports subscriptions on <input>, <textarea>, <select>, and [contenteditable="true"] elements, although it doesn't prevent you from subscribing on other types of elements. If you subscribe on a different type of element and stuff breaks, you were warned.

  • valuechange does not capture value updates done in JavaScript unless the input is currently focused and polling. It's meant to capture changes made by the user, not by other code. So: node.set('value', 'probably will not trigger valuechange');