up.layer up.layer.open([options])

JavaScript function

Render options to apply when opening the new overlay.

Common options are documented below, but most options for up.render() can be used.

You can configure default layer options in up.layer.config. For example, options in up.layer.config.overlay become defaults for all overlays, while options in up.layer.config.drawer become defaults for all drawers.

Whether to apply navigation defaults.

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

Whether to stack the new overlay or replace existing overlays.

The following values are supported:

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

When the overlay closes, the origin receives the focus 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.

For popups, the position of the popup relative to the link or button that opened the overlay. See popup position.

For drawers, the screen edge on which to position the drawer (left or right). See drawer position.

For popups, the alignment of the popup within its { position }. See popup position.

The URL to request from the server.

See loading content from a URL.

The HTTP method to use for the request.

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

Additional parameters that should be sent as the request's 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.

An object with additional request headers.

Unpoly will by default send a number of custom request headers. For example, the X-Up-Target header includes the targeted CSS selector. See up.protocol for details.

Whether to abort existing requests before rendering.

By default, opening a new overlay will abort all requests within the main element of its base layer.

See aborting requests for details and a list of options.

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 element

See Preventing a request from being aborted.

Whether this request will load in the background.

Background requests are deprioritized and won't show the progress bar. See Background requests.

The number of milliseconds after which this request can cause an up:network:late event and show the progress bar.

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

Defaults to up.network.config.lateDelay.

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

Defaults to up.network.config.timeout.

Whether to render error responses differently.

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

By default 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.

The new inner HTML for the targeted fragment.

See Updating an element's inner HTML from a string.

Instead of passing an HTML string you can also refer to a template.

A string of HTML comprising only the new fragment's outer HTML.

When passing { fragment } you can omit the { target } option. The target will be derived from the root element in the given HTML.

See Rendering a string that only contains the fragment.

Instead of passing an HTML string you can also refer to a template.

A string of HTML containing the targeted fragment.

See Extracting an element's outer HTML from a larger HTML string.

Instead of passing an HTML string you can also refer to a template.

An up.Response object that contains the targeted fragments in its text.

See Rendering an up.Response object.

The kind of overlay to open.

See available layer modes.

The size of the overlay.

Supported values are 'small', 'medium', 'large', and 'grow'.
See overlay sizes for details.

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

See overlay classes.

How the overlay can be dismissed by the user.

Supported values are 'key', 'outside', and 'button'.
See 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.

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

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

Whether to trap focus within the overlay while it is in front.

By default focus is trapped for all overlays except popups.

The data object for the overlay's root content element ({ target }).

If the content element already has an [up-data] attribute, properties from { data } take precedence.

The initial context object for the new overlay.

Whether the overlay has visible history.

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.

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.

See History in overlays.

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

See Rendering error responses differently.

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.

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.

Whether to update meta tags 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.

An explicit language code to set as the html[lang] 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.

The opening animation.

The timing function that controls the opening animation's acceleration.

The duration of the opening animation in milliseconds.

The closing animation.

The timing function that controls the closing animation's acceleration.

The duration of the closing animation in milliseconds.

One or more event types that will cause this overlay to automatically be accepted when a matching event occurs within the overlay.

The acceptance value is the event object that caused the overlay to close.

See Closing when an event is emitted.

One or more event types that will cause this overlay to automatically be dismissed when a matching event occurs within the overlay.

The dismissal value is the event object that caused the overlay to close.

See Closing when an event is emitted.

One or more URL patterns that will cause this overlay to automatically be accepted when the overlay reaches a matching location.

The acceptance value is an object of named segments matches captured by the URL pattern. It also contains the matched URL as a location key.

See Closing when a location is reached.

One or more URL patterns that will cause this overlay to automatically be dismissed when the overlay reaches a matching location.

The dismissal value is an object of named segments matches captured by the URL pattern. It also contains the matched URL as a location key.

See Closing when a location is reached.

A CSS selector that will cause this overlay to automatically be accepted when a matching element is observed within the overlay.

The acceptance value is the matching fragment's data object.
If the fragment has no data, the value is an empty object.

See Closing when a fragment is detected.

A CSS selector that will cause this overlay to automatically be dismissed when a matching element is observed within the overlay.

The dismissal value is the matching fragment's data object.
If the fragment has no data, the value is an empty object.

See Closing when a fragment is detected.

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

The function argument is an up:layer:opened 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 } option.

A function that is called when the overlay is about to be accepted.

The function argument is an up:layer:accept event. The overlay's acceptance value 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.

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

A function that is called when the overlay was accepted.

The function argument is an up:layer:accepted event.

A selector to reload after the overlay was accepted.

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.

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

See Subinteractions: Reloading on acceptance.

A function that is called when the overlay is about to be dismissed.

The function argument is an up:layer:dismiss event. The overlay's dismissal value 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.

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

A function that is called when the overlay was dismissed.

The function argument is an up:layer:dismissed event.

A selector to reload after the overlay was dismissed.

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.

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

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

The message will be shown as a native confirmation dialog.

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, also for showing a styled dialog instead of the browser's.

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

This callback will also run for error responses.

A callback that will be run when the fragment could not be loaded due to a disconnect or timeout.

The callback argument is an up:fragment:offline event. To try again, call event.retry().

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, 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.
• When revalidation renders a second time, { onRendered } is called again with the final result.

Also see Running code after rendering.

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

The following state is considered "finished":

• Animations have concluded and transitioned elements have been removed from the DOM tree.
• Async compilers have settled.
• Cached content has been revalidated with the server.
  If the server has responded with fresher content, that content has also been rendered.

The callback argument is the last up.RenderResult that updated a fragment. If 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, it is the result from the initial render pass.

To run a callback after an error response has finished rendering, pass an { onFailFinished } option instead.

When a 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.

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, or aborts.

Also see Handling errors.