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

# up.layer.open([options])

[Opens a new overlay](https://unpoly.com/learn/opening-overlays.md).

Opening a layer is considered [navigation](https://unpoly.com/learn/navigation-defaults.md) by default.

<nav aria-label="Guides">

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

</nav>

<nav aria-label="Contents">

#### Contents

- [Example](#example)
- [Parameters](#parameters)
- [Return value](#return-value)

</nav>

## Example {#example}

```js
let layer = await up.layer.open({ url: '/contacts' })
console.log(layer.mode) // logs "modal"
```

---

## Parameters {#parameters}

### Render options {#parameters-render-options}

#### [options] {#options}

(optional)

Render options to apply when opening the new overlay.

Common options are documented below, but most [options for `up.render()`](https://unpoly.com/api/up.render.md#parameters) can be used.

You can configure default layer options in [`up.layer.config`](https://unpoly.com/api/up.layer.config.md). For example, options in [`up.layer.config.overlay`](https://unpoly.com/api/up.layer.config.md#config.overlay) become defaults for all overlays, while options in [`up.layer.config.drawer`](https://unpoly.com/api/up.layer.config.md#config.drawer) become defaults for all drawers.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

#### [options.navigate=true] {#options.navigate}

(optional)

Whether to apply [navigation defaults](https://unpoly.com/learn/navigation-defaults.md).

Type: boolean

### Placement {#parameters-placement}

#### [options.target] {#options.target}

(optional)

The selector of the root content element to place inside the overlay container.

The given `{ target }` must be matchable within the HTML provided by either the `{ url }`, `{ content }`, `{ fragment }`, or `{ document }` option.

If the `{ target }` option is omitted, Unpoly will use the first matching [main target](https://unpoly.com/api/up-main.md) configured for the overlay mode. For example, the default selectors for modals are configured in `up.layer.config.modal.mainTargets`. See [main targets in overlays](https://unpoly.com/api/up-main.md#overlays).

Type: string

#### [options.layer="new"] {#options.layer}

(optional)

Whether to stack the new overlay or replace existing overlays.

The following values are supported:

| Option | Description |
| --- | --- |
| `new` | Stacks a new overlay over the current layer. |
| `swap` | Replaces the current overlay. If no overlay is open, opens an overlay. |
| `shatter` | Closes all overlays and opens a new overlay. |

Type: string

#### [options.origin] {#options.origin}

(optional)

The link or button element that caused this overlay to open.

When the overlay closes, the origin [receives the focus](https://unpoly.com/learn/focus.md#overlays) again. When you open an overlay from JavaScript, pass the element the user interacted with, e.g. `{ origin: event.target }` in an event handler. Without an origin, focus moves to the parent layer, and keyboard users lose their place on the page.

When opening a popup, the overlay is anchored relative to the origin element.

Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)

#### [options.position] {#options.position}

(optional)

For **popups**, the position of the popup relative to the link or button that opened the overlay. See [popup position](https://unpoly.com/learn/customizing-overlays.md#popup-position).

For **drawers**, the screen edge on which to position the drawer (`left` or `right`). See [drawer position](https://unpoly.com/learn/customizing-overlays.md#drawer-position).

Type: string

#### [options.align] {#options.align}

(optional)

For **popups**, the alignment of the popup within its `{ position }`. See [popup position](https://unpoly.com/learn/customizing-overlays.md#popup-position).

Type: string

### Request {#parameters-request}

#### [options.url] {#options.url}

(optional)

The URL to request from the server.

See [loading content from a URL](https://unpoly.com/learn/providing-html.md#url).

Type: string

#### [options.method='get'] {#options.method}

(optional)

The HTTP method to use for the request.

Common values are `'get'`, `'post'`, `'put'`, `'patch'` and `'delete'`. The value is case-insensitive.

Type: string

#### [options.params] {#options.params}

(optional)

Additional [parameters](https://unpoly.com/api/up.Params.md) that should be sent as the request's [query string](https://en.wikipedia.org/wiki/Query_string) or payload.

When making a `GET` request to a URL with a query string, the given `{ params }` will be added to the query parameters.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects) | [up.Params](https://unpoly.com/api/up.Params.md) | [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) | string | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

#### [options.headers={}] {#options.headers}

(optional)

An object with additional request headers.

Unpoly will by default send a number of custom request headers. For example, the [`X-Up-Target`](https://unpoly.com/api/X-Up-Target.md) header includes the [targeted](https://unpoly.com/learn/targeting-fragments.md) CSS selector. See [`up.protocol`](https://unpoly.com/api/up.protocol.md) for details.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

#### [options.abort='target'] {#options.abort}

(optional)

Whether to abort existing requests before rendering.

By default, opening a new overlay will abort all requests within the [main](https://unpoly.com/api/main.md) element of its base layer.

See [aborting requests](https://unpoly.com/learn/aborting-requests.md) for details and a list of options.

Type: boolean | string | Function(request): boolean

#### [options.abortable=true] {#options.abortable}

(optional)

Whether the request may be aborted by other requests.

By default, the request will be aborted:

- By another request opening another overlay from the same base layer
- By another request targeting the base layer's [main](https://unpoly.com/api/main.md) element

See [Preventing a request from being aborted](https://unpoly.com/learn/aborting-requests.md#preventing).

Type: boolean

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

(optional)

Whether this request will load in the background.

Background requests are deprioritized and won't show the [progress bar](https://unpoly.com/learn/progress-bar.md). See [Background requests](https://unpoly.com/learn/background-requests.md).

Type: boolean

#### [options.lateDelay] {#options.lateDelay}

(optional)

The number of milliseconds after which this request can cause an [`up:network:late`](https://unpoly.com/api/up:network:late.md) event and show the [progress bar](https://unpoly.com/learn/progress-bar.md).

To prevent the event and progress bar, pass `{ lateDelay: false }`.

Defaults to [`up.network.config.lateDelay`](https://unpoly.com/api/up.network.config.md#config.lateDelay).

Type: number | boolean

#### [options.timeout] {#options.timeout}

(optional)

The number of milliseconds after which this request fails with a timeout.

Defaults to [`up.network.config.timeout`](https://unpoly.com/api/up.network.config.md#config.timeout).

Type: number

#### [options.fail] {#options.fail}

(optional)

Whether to render [error responses](https://unpoly.com/learn/error-responses.md) differently.

Error responses will be rendered using options prefixed with `fail`, e.g. `{ failTarget }`.

By [default](https://unpoly.com/api/up.network.config.md#config.fail) any HTTP status code other than 2xx or 304 is considered an error response. Pass `{ fail: false }` to handle _any_ response as successful, even with a 4xx or 5xx status code.

Type: boolean | Function([up.Response](https://unpoly.com/api/up.Response.md)): boolean

### Local content {#parameters-local-content}

#### [options.content] {#options.content}

(optional)

The new [inner HTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML) for the targeted fragment.

See [Updating an element's inner HTML from a string](https://unpoly.com/learn/providing-html.md#content).

Instead of passing an HTML string you can also [refer to a template](https://unpoly.com/learn/templates.md).

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [List](https://unpoly.com/api/List.md)<[Node](https://developer.mozilla.org/en-US/docs/Web/API/Node)>

#### [options.fragment] {#options.fragment}

(optional)

A string of HTML comprising only the new fragment's [outer HTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML).

When passing `{ fragment }` you can omit the `{ target }` option. The target will be [derived](https://unpoly.com/learn/target-derivation.md) from the root element in the given HTML.

See [Rendering a string that only contains the fragment](https://unpoly.com/learn/providing-html.md#fragment).

Instead of passing an HTML string you can also [refer to a template](https://unpoly.com/learn/templates.md).

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)

#### [options.document] {#options.document}

(optional)

A string of HTML containing the targeted fragment.

See [Extracting an element's outer HTML from a larger HTML string](https://unpoly.com/learn/providing-html.md#document).

Instead of passing an HTML string you can also [refer to a template](https://unpoly.com/learn/templates.md).

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | Document

#### [options.response] {#options.response}

(optional)

An [`up.Response`](https://unpoly.com/api/up.Response.md) object that contains the targeted fragments in its [text](https://unpoly.com/api/up.Response.prototype.text.md).

See [Rendering an up.Response object](https://unpoly.com/learn/providing-html.md#response).

Type: [up.Response](https://unpoly.com/api/up.Response.md)

### Customization {#parameters-customization}

#### [options.mode] {#options.mode}

(optional)

The kind of overlay to open.

See [available layer modes](https://unpoly.com/learn/overlays.md#layer-modes).

Type: string

#### [options.size] {#options.size}

(optional)

The size of the overlay.

Supported values are `'small'`, `'medium'`, `'large'`, and `'grow'`.
See [overlay sizes](https://unpoly.com/learn/customizing-overlays.md#overlay-sizes) for details.

Type: string

#### [options.class] {#options.class}

(optional)

An optional HTML class for the overlay's container element.

See [overlay classes](https://unpoly.com/learn/customizing-overlays.md#overlay-classes).

Type: string

#### [options.dismissible=true] {#options.dismissible}

(optional)

How the overlay can be [dismissed](https://unpoly.com/learn/closing-overlays.md) by the user.

Supported values are `'key'`, `'outside'`, and `'button'`.
See [customizing dismiss controls](https://unpoly.com/learn/customizing-overlays.md#customizing-dismiss-controls) for details.

You can enable multiple dismiss controls by passing an array or a space-separated string.

Passing `true` or `false` will enable or disable all dismiss controls.

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

#### [options.dismissLabel] {#options.dismissLabel}

(optional)

The label for the dismiss icon in the top-right corner.

Type: string

#### [options.dismissARIALabel] {#options.dismissARIALabel}

(optional)

The accessibility label for the dismiss icon in the top-right corner.

Type: string

#### [options.trapFocus] {#options.trapFocus}

(optional)

Whether to [trap focus](https://unpoly.com/learn/focus.md#overlay-focus-trap) within the overlay while it is in [front](https://unpoly.com/api/up.layer.front.md).

By default focus is trapped for all overlays except [popups](https://unpoly.com/learn/overlays.md#layer-modes).

Type: boolean

### Client state {#parameters-client-state}

#### [options.data] {#options.data}

(optional)

The [data object](https://unpoly.com/learn/data.md) for the overlay's root content element (`{ target }`).

If the content element already has an [`[up-data]`](https://unpoly.com/api/up-data.md) attribute, properties from `{ data }` take precedence.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

#### [options.context={}] (Experimental) {#options.context}

(optional)

The initial [context](https://unpoly.com/api/up.layer.context.md) object for the new overlay.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

### History {#parameters-history}

#### [options.history] {#options.history}

(optional)

Whether the overlay has [visible history](https://unpoly.com/learn/history-in-overlays.md).

If set to `true`, the overlay location, title, and meta tags will be shown while the overlay is open. When the overlay is closed, the parent layer's history is restored.

If set to `'auto'`, history will be visible if the initial overlay content matches a [main target](https://unpoly.com/api/up-main.md).

If set to `false`, fragment changes within the overlay will _never_ update the address bar. You can still access the overlay's current location using [`up.layer.location`](https://unpoly.com/api/up.layer.location.md).

See [History in overlays](https://unpoly.com/learn/history-in-overlays.md).

Type: boolean | string

#### [options.failHistory] {#options.failHistory}

(optional)

Whether to update history when the server responds with an error code.

See [Rendering error responses differently](https://unpoly.com/learn/error-responses.md#fail-options).

Type: boolean | string

#### [options.title] {#options.title}

(optional)

An explicit document title to set before rendering.

By default the title is extracted from the response's `<title>` tag. To prevent the title from being updated, pass `{ title: false }`.

This option is only used when [updating history](#options.history).

Type: boolean | string

#### [options.location] {#options.location}

(optional)

An explicit browser location URL to set before rendering.

By default Unpoly will use the `{ url }` or the final URL after the server redirected. To prevent the URL from being updated, pass `{ location: false }`.

This option is only used when [updating history](#options.history).

Type: boolean | string

#### [options.metaTags] {#options.metaTags}

(optional)

Whether to update [meta tags](https://unpoly.com/api/up-meta.md) in the `<head>`.

By default Unpoly will extract meta tags from the response's `<head>`. To prevent meta tags from being updated, pass `{ metaTags: false }`.

This option is only used when [updating history](#options.history).

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

#### [options.lang] {#options.lang}

(optional)

An explicit language code to set as the [`html[lang]`](https://www.tpgi.com/using-the-html-lang-attribute/) attribute.

By default Unpoly will extract the language from the response and update the `html[lang]` attribute in the current page. To prevent the attribute from being changed, pass `{ lang: false }`.

This option is only used when [updating history](#options.history).

Type: boolean | string

### Animation {#parameters-animation}

#### [options.animation='fade-in'] {#options.animation}

(optional)

The opening animation.

Type: string | Function | boolean

#### [options.easing='ease'] {#options.easing}

(optional)

The [timing function](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) that controls the opening animation's acceleration.

Type: string

#### [options.duration=175] {#options.duration}

(optional)

The duration of the opening animation in milliseconds.

Type: number

#### [options.closeAnimation='fade-out'] {#options.closeAnimation}

(optional)

The closing animation.

Type: string | Function | boolean

#### [options.closeEasing='ease'] {#options.closeEasing}

(optional)

The [timing function](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) that controls the closing animation's acceleration.

Type: string

#### [options.closeDuration=175] {#options.closeDuration}

(optional)

The duration of the closing animation in milliseconds.

Type: number

### Close conditions {#parameters-close-conditions}

#### [options.acceptEvent] {#options.acceptEvent}

(optional)

One or more event types that will cause this overlay to automatically be [accepted](https://unpoly.com/learn/closing-overlays.md) when a matching event occurs within the overlay.

The [acceptance value](https://unpoly.com/learn/closing-overlays.md#acceptance-values) is the event object that caused the overlay to close.

See [Closing when an event is emitted](https://unpoly.com/learn/subinteractions.md#event-condition).

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

#### [options.dismissEvent] {#options.dismissEvent}

(optional)

One or more event types that will cause this overlay to automatically be [dismissed](https://unpoly.com/learn/closing-overlays.md) when a matching event occurs within the overlay.

The [dismissal value](https://unpoly.com/learn/closing-overlays.md#dismissal-values) is the event object that caused the overlay to close.

See [Closing when an event is emitted](https://unpoly.com/learn/subinteractions.md#event-condition).

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

#### [options.acceptLocation] {#options.acceptLocation}

(optional)

One or more [URL patterns](https://unpoly.com/api/url-patterns.md) that will cause this overlay to automatically be [accepted](https://unpoly.com/learn/closing-overlays.md) when the overlay reaches a matching [location](https://unpoly.com/api/up.layer.location.md).

The [acceptance value](https://unpoly.com/learn/closing-overlays.md#acceptance-values) is an object of [named segments matches](https://unpoly.com/api/url-patterns.md#capturing-named-segments) captured by the URL pattern. It also contains the matched URL as a `location` key.

See [Closing when a location is reached](https://unpoly.com/learn/subinteractions.md#location-condition).

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

#### [options.dismissLocation] {#options.dismissLocation}

(optional)

One or more [URL patterns](https://unpoly.com/api/url-patterns.md) that will cause this overlay to automatically be [dismissed](https://unpoly.com/learn/closing-overlays.md) when the overlay reaches a matching [location](https://unpoly.com/api/up.layer.location.md).

The [dismissal value](https://unpoly.com/learn/closing-overlays.md#dismissal-values) is an object of [named segments matches](https://unpoly.com/api/url-patterns.md#capturing-named-segments) captured by the URL pattern. It also contains the matched URL as a `location` key.

See [Closing when a location is reached](https://unpoly.com/learn/subinteractions.md#location-condition).

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

#### [options.acceptFragment] {#options.acceptFragment}

(optional)

A CSS selector that will cause this overlay to automatically be [accepted](https://unpoly.com/learn/closing-overlays.md) when a matching element is observed within the overlay.

The [acceptance value](https://unpoly.com/learn/closing-overlays.md#acceptance-values) is the matching fragment's [data](https://unpoly.com/learn/data.md) object.
If the fragment has no data, the value is an empty object.

See [Closing when a fragment is detected](https://unpoly.com/learn/subinteractions.md#fragment-condition).

Type: string

#### [options.dismissFragment] {#options.dismissFragment}

(optional)

A CSS selector that will cause this overlay to automatically be [dismissed](https://unpoly.com/learn/closing-overlays.md) when a matching element is observed within the overlay.

The [dismissal value](https://unpoly.com/learn/closing-overlays.md#dismissal-values) is the matching fragment's [data](https://unpoly.com/learn/data.md) object.
If the fragment has no data, the value is an empty object.

See [Closing when a fragment is detected](https://unpoly.com/learn/subinteractions.md#fragment-condition).

Type: string

### Callbacks {#parameters-callbacks}

#### [options.onOpened] {#options.onOpened}

(optional)

A function that is called when the overlay was inserted into the DOM.

The function argument is an [`up:layer:opened`](https://unpoly.com/api/up:layer:opened.md) event.

The overlay may still play an opening animation when this function is called. To be called when the opening animation is done, pass an [`{ onFinished }`](https://unpoly.com/api/up.render.md#options.onFinished) option.

Type: Function([Event](https://developer.mozilla.org/en-US/docs/Web/API/Event))

#### [options.onAccept] {#options.onAccept}

(optional)

A function that is called when the overlay is about to be [accepted](https://unpoly.com/learn/closing-overlays.md).

The function argument is an [`up:layer:accept`](https://unpoly.com/api/up:layer:accept.md) event. The overlay's [acceptance value](https://unpoly.com/learn/closing-overlays.md#acceptance-values) is available as `event.value`.

To keep the overlay open, call `event.preventDefault()`. This has no effect when the overlay is closed because a background layer is being [updated](https://unpoly.com/learn/closing-overlays.md#peeling).

To run code after the overlay closed, use `{ onAccepted }` instead.

Type: Function([Event](https://developer.mozilla.org/en-US/docs/Web/API/Event))

#### [options.onAccepted] {#options.onAccepted}

(optional)

A function that is called when the overlay was [accepted](https://unpoly.com/learn/closing-overlays.md).

The function argument is an [`up:layer:accepted`](https://unpoly.com/api/up:layer:accepted.md) event.

Type: Function([Event](https://developer.mozilla.org/en-US/docs/Web/API/Event))

#### [options.onAcceptedReload] (Experimental) {#options.onAcceptedReload}

(optional)

A selector to [reload](https://unpoly.com/api/up.reload.md) after the overlay was [accepted](https://unpoly.com/learn/closing-overlays.md).

The element is looked up in the layer that opened the overlay. An element near the `{ origin }` is preferred, and the selector may use [`:origin`](https://unpoly.com/api/origin.md).

When an `{ onAccepted }` callback is also set, it runs first.

See [Subinteractions: Reloading on acceptance](https://unpoly.com/learn/subinteractions.md#reloading-on-acceptance).

Type: string

#### [options.onDismiss] {#options.onDismiss}

(optional)

A function that is called when the overlay is about to be [dismissed](https://unpoly.com/learn/closing-overlays.md).

The function argument is an [`up:layer:dismiss`](https://unpoly.com/api/up:layer:dismiss.md) event. The overlay's [dismissal value](https://unpoly.com/learn/closing-overlays.md#dismissal-values) is available as `event.value`.

To keep the overlay open, call `event.preventDefault()`. This has no effect when the overlay is closed because a background layer is being [updated](https://unpoly.com/learn/closing-overlays.md#peeling).

To run code after the overlay closed, use `{ onDismissed }` instead.

Type: Function([Event](https://developer.mozilla.org/en-US/docs/Web/API/Event))

#### [options.onDismissed] {#options.onDismissed}

(optional)

A function that is called when the overlay was [dismissed](https://unpoly.com/learn/closing-overlays.md).

The function argument is an [`up:layer:dismissed`](https://unpoly.com/api/up:layer:dismissed.md) event.

Type: Function([Event](https://developer.mozilla.org/en-US/docs/Web/API/Event))

#### [options.onDismissedReload] (Experimental) {#options.onDismissedReload}

(optional)

A selector to [reload](https://unpoly.com/api/up.reload.md) after the overlay was [dismissed](https://unpoly.com/learn/closing-overlays.md).

The element is looked up in the layer that opened the overlay. An element near the `{ origin }` is preferred, and the selector may use [`:origin`](https://unpoly.com/api/origin.md).

When an `{ onDismissed }` callback is also set, it runs first.

Type: string

#### [options.confirm] {#options.confirm}

(optional)

A message the user needs to confirm before any request or changes are made.

The message will be shown as a [native confirmation dialog](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm).

If the user does not confirm, no request is sent and no fragments are updated. In that case the render promise rejects with an `up.Aborted` error.

See [Confirmation dialogs](https://unpoly.com/learn/confirmation-dialogs.md), also for showing a styled dialog instead of the browser's.

Type: string

#### [options.onLoaded] {#options.onLoaded}

(optional)

A callback that will be run when the server responds with new HTML, but before the HTML is rendered.

The callback argument is a preventable [`up:fragment:loaded`](https://unpoly.com/api/up:fragment:loaded.md) event.

This callback will also run for [error responses](https://unpoly.com/learn/error-responses.md).

Type: Function([Event](https://developer.mozilla.org/en-US/docs/Web/API/Event))

#### [options.onOffline] {#options.onOffline}

(optional)

A callback that will be run when the fragment could not be loaded due to a [disconnect or timeout](https://unpoly.com/learn/network-issues.md).

The callback argument is an [`up:fragment:offline`](https://unpoly.com/api/up:fragment:offline.md) event. To try again, call `event.retry()`.

Type: Function([Event](https://developer.mozilla.org/en-US/docs/Web/API/Event))

#### [options.onRendered] {#options.onRendered}

(optional)

A function to call when Unpoly has updated fragments.

This callback may be called zero, one or two times:

- When the server rendered an [empty response](https://unpoly.com/learn/conditional-requests.md#rendering-nothing), no fragments are updated. `{ onRendered }` is not called.
- When the server rendered a matching fragment, it will be updated on the page. `{ onRendered }` is called with the [result](https://unpoly.com/api/up.RenderResult.md).
- When [revalidation](https://unpoly.com/learn/caching.md#revalidation) renders a second time, `{ onRendered }` is called again with the final result.

Also see [Running code after rendering](https://unpoly.com/learn/render-lifecycle.md#running-code-after-rendering).

Type: Function([up.RenderResult](https://unpoly.com/api/up.RenderResult.md))

#### [options.onFinished] {#options.onFinished}

(optional)

A function to call when no further DOM changes will be caused by this render pass.

The following state is considered "finished":

- [Animations](https://unpoly.com/api/up.motion.md) have concluded and [transitioned](https://unpoly.com/api/up-transition.md) elements have been removed from the DOM tree.
- [Async compilers](https://unpoly.com/api/up.compiler.md#async) have settled.
- [Cached content](https://unpoly.com/learn/caching.md) has been [revalidated with the server](https://unpoly.com/learn/caching.md#revalidation).
  If the server has responded with fresher content, that content has also been rendered.

The callback argument is the last [`up.RenderResult`](https://unpoly.com/api/up.RenderResult.md) that updated a fragment. If [revalidation](https://unpoly.com/learn/caching.md#revalidation) re-rendered the fragment, it is the result from the second render pass. If no revalidation was performed, or if revalidation yielded an [empty response](https://unpoly.com/learn/caching.md#when-nothing-changed), it is the result from the initial render pass.

To run a callback after an [error response](https://unpoly.com/learn/error-responses.md) has finished rendering, pass an `{ onFailFinished }` option instead.

When a [revalidation](https://unpoly.com/learn/caching.md#revalidation) receives an error response, `{ onFinished }` is not called. Instead `{ onFailRendered }` and `{ onFailFinished }` are called for the revalidation's error response.

Also see [Awaiting post-processing](https://unpoly.com/learn/render-lifecycle.md#postprocessing).

Type: Function([up.RenderResult](https://unpoly.com/api/up.RenderResult.md))

#### [options.onError] {#options.onError}

(optional)

A callback that will be run when any error is thrown during the rendering process.

The callback is also called when the render pass fails due to [network issues](https://unpoly.com/learn/network-issues.md), or [aborts](https://unpoly.com/learn/aborting-requests.md).

Also see [Handling errors](https://unpoly.com/learn/render-lifecycle.md#handling-errors).

Type: Function([Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error))

---

## Return value {#return-value}

A promise for the [`up.Layer`](https://unpoly.com/api/up.Layer.md) object that describes the new overlay.

The promise is fulfilled once the overlay was placed into the DOM. At this time an overlay's opening animation will still be playing.

Type: [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)<[up.Layer](https://unpoly.com/api/up.Layer.md)>