up.event up.on([element], types, [selector], [options], listener)

JavaScript function

Listens to a DOM event on document or a given element.

up.on() has some quality of life improvements over Element#addEventListener():

• You may pass a selector for event delegation.
• The event target is automatically passed as a second argument.
• Your event listener will not be called when Unpoly has not booted in an unsupported browser
• You may register a listener to multiple events by passing a space-separated list of event name (e.g. "click mousedown")
• You may register a listener to multiple elements in a single up.on() call, by passing a list of elements.
• Any data attached to the observed element will be passed as a third argument to your handler function.

You can prevent the event from being processed further with up.event.halt(event).

Basic example

The code below will call the listener when a <a> is clicked anywhere in the document:

up.on('click', 'a', function(event, element) {
  console.log("Click on a link %o", element)
})

You may also bind the listener to a given element instead of document:

var form = document.querySelector('form')
up.on(form, 'click', function(event, form) {
  console.log("Click within %o", form)
})

Event delegation

You may pass both an element and a selector for event delegation.

The example below registers a single event listener to the given form, but only calls the listener when the clicked element is a select element:

var form = document.querySelector('form')
up.on(form, 'click', 'select', function(event, select) {
  console.log("Click on select %o within %o", select, form)
})

Attaching data

Any data attached to the observed element will be passed to your event handler.

For instance, this element has attached data in its [up-data] attribute:

<span class='user' up-data='{ "age": 18, "name": "Bob" }'>Bob</span>

The parsed data will be passed to your event handler as a third argument:

up.on('click', '.user', function(event, element, data) {
  console.log("This is %o who is %o years old", data.name, data.age)
})

Unbinding an event listener

up.on() returns a function that unbinds the event listeners when called:

// Define the listener
var listener =  function(event) { ... }

// Binding the listener returns an unbind function
var unbind = up.on('click', listener)

// Unbind the listener
unbind()

There is also a function up.off() which you can use for the same purpose:

// Define the listener
var listener =  function(event) { ... }

// Bind the listener
up.on('click', listener)

// Unbind the listener
up.off('click', listener)

Binding to multiple elements

You may register a listener to multiple elements in a single up.on() call, by passing a list of elements:

let allForms = document.querySelectorAll('form')
up.on(allForms, 'submit', function(event, form) {
  console.log('Submitting form %o', form)
})

Binding to multiple event types

You may register a listener to multiple event types by passing a space-separated list of event types:

let element = document.querySelector(...)
up.on(element, 'mouseenter mouseleave', function(event) {
  console.log('Mouse entered or left')
})