---
name: "up.layer"
area: "API"
kind: "module"
parent: "API reference"
url: "https://unpoly.com/api/up.layer"
---
<nav aria-label="Unpoly docs">[All docs](https://unpoly.com/index.md) · [API reference](https://unpoly.com/api.md)</nav>

# `up.layer`

Features to open, close and look up overlays.

Add [`[up-layer=new]`](https://unpoly.com/api/up-layer-new.md) to a link or form to show its response in a new overlay, or open one from JavaScript with [`up.layer.open()`](https://unpoly.com/api/up.layer.open.md). An overlay closes when the user dismisses it, or when an [`[up-accept]`](https://unpoly.com/api/up-accept.md) link or form closes it with a result value. [`up.layer.ask()`](https://unpoly.com/api/up.layer.ask.md) opens an overlay and returns a promise for that value, so a subinteraction reads like a function call.

[`up.layer.current`](https://unpoly.com/api/up.layer.current.md) is the layer your code is working with, and most functions in this module operate on it: [`up.layer.on()`](https://unpoly.com/api/up.layer.on.md) listens to events from the current layer only, and [`up.layer.dismiss()`](https://unpoly.com/api/up.layer.dismiss.md) closes it. The layers themselves are [`up.Layer`](https://unpoly.com/api/up.Layer.md) objects, listed in [`up.layer.stack`](https://unpoly.com/api/up.layer.stack.md).

<nav aria-label="Guides">

- [Learn: Overlays](https://unpoly.com/learn/overlays.md)

</nav>

---

## Features {#features}

- ### [[up-accept]](https://unpoly.com/api/up-accept.md) (HTML attribute)

  Accepts the current layer when this element is clicked or submitted.

- ### [[up-close]](https://unpoly.com/api/up-close.md) (HTML attribute) (deprecated)

  When this element is clicked, closes a currently open overlay.

- ### [[up-dismiss]](https://unpoly.com/api/up-dismiss.md) (HTML attribute)

  Dismisses the current layer when this element is clicked or submitted.

- ### [[up-drawer]](https://unpoly.com/api/up-drawer.md) (HTML attribute) (deprecated)

  Clicking this link will load the destination and open the given selector in a drawer overlay that slides in from the edge of the screen.

- ### [up.layer.accept([value], [options])](https://unpoly.com/api/up.layer.accept.md) (JavaScript function)

  Accepts the current layer.

- ### [up:layer:accept](https://unpoly.com/api/up:layer:accept.md) (DOM event)

  This event is emitted _before_ a layer is accepted.

- ### [up:layer:accepted](https://unpoly.com/api/up:layer:accepted.md) (DOM event)

  This event is emitted _after_ a layer was accepted.

- ### [up.layer.affix(selector, [attrs])](https://unpoly.com/api/up.layer.affix.md) (JavaScript function) (experimental)

  Creates an element with the given `selector` and appends it to the current layer's content.

- ### [up.layer.ask([options])](https://unpoly.com/api/up.layer.ask.md) (JavaScript function)

  Opens an overlay and returns a promise for its acceptance.

- ### [up.layer.config](https://unpoly.com/api/up.layer.config.md) (Configuration object)

  Configures default attributes for new overlays.

- ### [up.layer.contains(element)](https://unpoly.com/api/up.layer.contains.md) (JavaScript function)

  Returns whether the given `element` is contained by the current layer.

- ### [up.layer.context](https://unpoly.com/api/up.layer.context.md) (JavaScript property) (experimental)

  The context of the current layer.

- ### [up.layer.count](https://unpoly.com/api/up.layer.count.md) (JavaScript property)

  Returns the number of layers in the layer stack.

- ### [up.layer.current](https://unpoly.com/api/up.layer.current.md) (JavaScript property)

  Returns the current layer in the layer stack.

- ### [up.layer.dismiss([value], [options])](https://unpoly.com/api/up.layer.dismiss.md) (JavaScript function)

  Dismisses the current layer.

- ### [up:layer:dismiss](https://unpoly.com/api/up:layer:dismiss.md) (DOM event)

  This event is emitted _before_ a layer is dismissed.

- ### [up:layer:dismissed](https://unpoly.com/api/up:layer:dismissed.md) (DOM event)

  This event is emitted _after_ a layer was dismissed.

- ### [up.layer.dismissOverlays([value], [options])](https://unpoly.com/api/up.layer.dismissOverlays.md) (JavaScript function)

  Dismisses all overlays.

- ### [up.layer.element](https://unpoly.com/api/up.layer.element.md) (JavaScript property)

  The outmost element of the current layer.

- ### [up.layer.emit(eventType, [props])](https://unpoly.com/api/up.layer.emit.md) (JavaScript function)

  Emits an event on the current layer's element.

- ### [up.layer.front](https://unpoly.com/api/up.layer.front.md) (JavaScript property)

  Returns the frontmost layer in the layer stack.

- ### [up.layer.get([value])](https://unpoly.com/api/up.layer.get.md) (JavaScript function)

  Returns an `up.Layer` object for the given element or layer option.

- ### [up.layer.getAll([layer])](https://unpoly.com/api/up.layer.getAll.md) (JavaScript function) (experimental)

  Returns an array of `up.Layer` objects matching the given layer option.

- ### [up.layer.history](https://unpoly.com/api/up.layer.history.md) (JavaScript property)

  Whether the current layer has visible history.

- ### [up.layer.isFront()](https://unpoly.com/api/up.layer.isFront.md) (JavaScript function)

  Returns whether the current layer is the frontmost layer.

- ### [up.layer.isOverlay()](https://unpoly.com/api/up.layer.isOverlay.md) (JavaScript function)

  Returns whether the current layer is _not_ the root layer.

- ### [up.layer.isRoot()](https://unpoly.com/api/up.layer.isRoot.md) (JavaScript function)

  Returns whether the current layer is the root layer.

- ### [up.layer.location](https://unpoly.com/api/up.layer.location.md) (JavaScript property)

  The location URL of the current layer.

- ### [up:layer:location:changed](https://unpoly.com/api/up:layer:location:changed.md) (DOM event)

  This event is emitted after a layer's location property has changed value.

- ### [up.layer.mode](https://unpoly.com/api/up.layer.mode.md) (JavaScript property)

  The current layer's mode, which governs its appearance and behavior.

- ### [[up-layer=new]](https://unpoly.com/api/up-layer-new.md) (HTML attribute)

  Shows the response to a link click or form submission within a new overlay.

- ### [up.layer.off(types, listener)](https://unpoly.com/api/up.layer.off.md) (JavaScript function)

  Unbinds an event listener previously bound to the current layer.

- ### [up.layer.on(types, [selector], [options], listener)](https://unpoly.com/api/up.layer.on.md) (JavaScript function)

  Listens to a DOM event that originated on an element contained by the current layer.

- ### [up.layer.open([options])](https://unpoly.com/api/up.layer.open.md) (JavaScript function)

  Opens a new overlay.

- ### [up:layer:open](https://unpoly.com/api/up:layer:open.md) (DOM event)

  This event is emitted before an overlay is opened.

- ### [up:layer:opened](https://unpoly.com/api/up:layer:opened.md) (DOM event)

  This event is emitted after a new overlay was placed into the DOM.

- ### [up.layer.overlays](https://unpoly.com/api/up.layer.overlays.md) (JavaScript property)

  Returns an array of all overlays.

- ### [up.layer.parent](https://unpoly.com/api/up.layer.parent.md) (JavaScript property)

  Returns the parent layer of the current layer.

- ### [up.layer.root](https://unpoly.com/api/up.layer.root.md) (JavaScript property)

  Returns the root layer.

- ### [up.layer.size](https://unpoly.com/api/up.layer.size.md) (JavaScript property)

  The size of the current layer.

- ### [up.layer.stack](https://unpoly.com/api/up.layer.stack.md) (JavaScript property)

  A list of layers that are currently open.

- ### [[up-modal]](https://unpoly.com/api/up-modal.md) (HTML attribute) (deprecated)

  Clicking this link will load the destination and open the given selector in a modal overlay.

- ### [up.modal.close(options)](https://unpoly.com/api/up.modal.close.md) (JavaScript function) (deprecated)

  Closes a currently open overlay.

- ### [up.modal.config](https://unpoly.com/api/up.modal.config.md) (Configuration object) (deprecated)

  Sets default options for future modal overlays.

- ### [up.modal.contains(elementOrSelector)](https://unpoly.com/api/up.modal.contains.md) (JavaScript function) (deprecated)

  Returns whether the given element or selector is contained within the current layer.

- ### [up.modal.coveredUrl()](https://unpoly.com/api/up.modal.coveredUrl.md) (JavaScript function) (deprecated)

  Returns the location URL of the layer behind the current overlay.

- ### [up.modal.extract(selector, document, options)](https://unpoly.com/api/up.modal.extract.md) (JavaScript function) (deprecated)

  Extracts the given CSS selector from the given HTML string and opens the results in a modal overlay.

- ### [up.modal.follow(linkOrSelector, [options])](https://unpoly.com/api/up.modal.follow.md) (JavaScript function) (deprecated)

  Opens the given link's destination in a modal overlay.

- ### [up.modal.isOpen()](https://unpoly.com/api/up.modal.isOpen.md) (JavaScript function) (deprecated)

  Returns whether an overlay is currently open.

- ### [up.modal.url()](https://unpoly.com/api/up.modal.url.md) (JavaScript function) (deprecated)

  Returns the location URL of the fragment displayed in the current overlay.

- ### [up.modal.visit(url, options)](https://unpoly.com/api/up.modal.visit.md) (JavaScript function) (deprecated)

  Opens a modal overlay for the given URL.

- ### [[up-popup]](https://unpoly.com/api/up-popup.md) (HTML attribute) (deprecated)

  Clicking this link will load the destination and open the given selector in a popup overlay.

- ### [up.popup.attach(anchor, [options])](https://unpoly.com/api/up.popup.attach.md) (JavaScript function) (deprecated)

  Attaches a popup overlay to the given element or selector.

- ### [up.popup.close(options)](https://unpoly.com/api/up.popup.close.md) (JavaScript function) (deprecated)

  Closes a currently open overlay.

- ### [up.popup.config](https://unpoly.com/api/up.popup.config.md) (Configuration object) (deprecated)

  Sets default options for future popup overlays.

- ### [up.popup.contains(elementOrSelector)](https://unpoly.com/api/up.popup.contains.md) (JavaScript function) (deprecated)

  Returns whether the given element or selector is contained within the current layer.

- ### [up.popup.coveredUrl()](https://unpoly.com/api/up.popup.coveredUrl.md) (JavaScript function) (deprecated)

  Returns the location URL of the layer behind the current overlay.

- ### [up.popup.isOpen()](https://unpoly.com/api/up.popup.isOpen.md) (JavaScript function) (deprecated)

  Returns whether an overlay is currently open.

- ### [up.popup.url()](https://unpoly.com/api/up.popup.url.md) (JavaScript function) (deprecated)

  Returns the location URL of the fragment displayed in the current overlay.