---
name: "up.Layer.prototype.on"
area: "API"
kind: "Instance method"
parent: "up.Layer class"
url: "https://unpoly.com/api/up.Layer.prototype.on"
---
<nav aria-label="Unpoly docs">[All docs](https://unpoly.com/index.md) · [up.Layer class](https://unpoly.com/api/up.Layer.md)</nav>

# up.Layer.prototype.on(types, [selector], [options], listener)

Listens to a [DOM event](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Events) that originated on an element [contained](https://unpoly.com/api/up.Layer.prototype.contains.md) by this layer.

This will ignore events emitted on elements in [descendant](https://unpoly.com/api/up.Layer.prototype.descendants.md) overlays, even if the descendant overlay's element is nested into the DOM tree of this layer.

The arguments for this function are the same as for [`up.on()`](https://unpoly.com/api/up.on.md).

<nav aria-label="Contents">

#### Contents

- [Example](#example)
- [Most Unpoly events have a layer reference](#most-unpoly-events-have-a-layer-reference)
- [Parameters](#parameters)
- [Return value](#return-value)

</nav>

## Example {#example}

```js
let rootLayer = up.layer.root
let overlay = await up.layer.open()

rootLayer.on('foo', (event) => console.log('Listener called'))

rootLayer.emit('foo') // logs "Listener called"
overlay.emit('foo')   // listener is not called
```

## Most Unpoly events have a layer reference {#most-unpoly-events-have-a-layer-reference}

Whenever possible Unpoly will emit its events on associated layers instead of `document`. This way you can listen to events on one layer without receiving events from other layers.

E.g. to listen to all [requests](https://unpoly.com/api/up.request.md) originating from a given layer:

```js
let rootLayer = up.layer.root
let rootLink = rootLayer.affix('a[href=/foo]')

let overlay = await up.layer.open()
let overlayLink = overlay.affix('a[href=/bar]')

rootLayer.on('up:request:load', (event) => console.log('Listener called'))

up.follow(rootLink)    // logs "Listener called"
up.follow(overlayLink) // listener is not called
```

---

## Parameters {#parameters}

### Observed events {#parameters-observed-events}

#### types {#types}

(required)

The event types to bind to.

Multiple event types may be passed as either a space-separated string (`'foo bar'`), a comma-separated string (`'foo, bar'`) or as an array of types (`['foo', 'bar']`).

Type: string | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string>

#### [selector] {#selector}

(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.

Type: string | Function():string

### Listener {#parameters-listener}

#### [options.passive=false] {#options.passive}

(optional)

Whether to register a [passive event listener](https://developers.google.com/web/updates/2016/06/passive-event-listeners).

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

Type: boolean

#### [options.once=false] {#options.once}

(optional)

Whether the listener should run at most once.

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

Type: boolean

#### [options.capture=false] {#options.capture}

(optional)

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

See [event capturing](https://javascript.info/bubbling-and-capturing#capturing) for more information about DOM event processing phases.

Type: boolean

#### listener {#listener}

(required)

The listener function that should be called.

The function takes the observed element as a second argument. The element's [attached data](https://unpoly.com/learn/data.md) is passed as a third argument.

Type: Function(event, [element], [[data](https://unpoly.com/learn/data.md)])

---

## Return value {#return-value}

A function that unbinds the event listeners when called.

Type: Function()