Edit this page

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')
})

Parameters

[element=document] ElementorjQuery optional

The element on which to register the event listener.

If no element is given, the listener is registered on the document.

types stringorArray<string>

The event types to bind to.

Multiple event types may be passed as either a space-separated string or as an array of types.

[selector] stringorFunction():string optional

The selector of an element on which the event must be triggered.

Omit the selector to listen to all events of the given type, regardless of the event target.

If the selector is not known in advance you may also pass a function that returns the selector. The function is evaluated every time an event with the given type is observed.

[options.passive=false] boolean optional

Whether to register a passive event listener.

A passive event listener may not call event.preventDefault(). This in particular may improve the frame rate when registering touchstart and touchmove events.

[options.once=true] boolean optional

Whether the listener should run at most once.

If true the listener will automatically be unbound after the first invocation.

[options.capture=false] boolean optional

Whether the listener should run before the event is emitted on the element.

See event capturing for more information about DOM event processing phases.

listener Function(event, [element], [data])

The listener function that should be called.

The function takes the observed element as a second argument. The element's attached data is passed as a third argument.

Return value

Function()

A function that unbinds the event listeners when called.