Edit this page

up.layer [up-layer=new]
HTML selector

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

Opening overlays

Example

This link will open its response in a modal overlay:

<a href="/menu" up-layer="new">Open menu</a> <!-- mark: up-layer -->

This form will show error messages from a failed submission within a modal overlay:

<form action="/submit" up-fail-layer="new"> <!-- mark: up-fail-layer -->
  ...
</form>

Info

All modifying attributes for [up-follow] (links) or [up-submit] (forms) can also be used.
Default layer attributes can be configured in up.layer.config.

Placement

[up-target]
optional

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

The target must be matchable within the HTML provided by either [href], [up-content], [up-fragment] or [up-document] option.

If the attribute is emitted, Unpoly will use the first matching main target configured for the overlay mode. E.g. the default selectors for modals are configured in up.layer.config.modal.mainTargets. See main targets in overlays.

[up-layer="new"]
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.
string
[up-position]
optional

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.

string
[up-align]
optional

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

string

Request

[href]
optional

The URL to fetch from the server.

See loading content from a URL.

To use a different URL when a link is followed through Unpoly (as opposed to a browser's full page load), set an [up-href] attribute.

Instead of making a server request, you may also render an existing string of HTML.

[up-method='get']
optional

The HTTP method to use for the request.

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

The HTTP method may also be passed as an [data-method] attribute.

By default, methods other than get or post will be converted into a post request, and carry their original method as a configurable _method parameter.

[up-params]
optional

A relaxed JSON object with 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.

[up-headers]
optional

A relaxed JSON object with additional request headers.

Unpoly will by default send a number of custom request headers. E.g. the X-Up-Target header includes the target selector. See up.protocol for details.

[up-abort='target']
optional

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.

[up-abortable='true']
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 element

See Preventing a request from being aborted.

[up-background='false']
optional

Whether this request will load in the background.

Background requests deprioritized over foreground requests. Background requests also won't emit up:network:late events and won't trigger the progress bar.

[up-late-delay]
optional

The number of milliseconds after which this request can cause an up:network:late event.

Defaults to up.network.config.lateDelay.

[up-timeout]
optional

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

Defaults to up.network.config.timeout.

[up-fail]
optional

Whether to render failed responses differently.

For failed responses Unpoly will use attributes prefixed with up-fail, e.g. [up-fail-target].

By default any HTTP status code other than 2xx or 304 is considered an error code. Set [up-fail=false] to handle any response as successful, even with a 4xx or 5xx status code.

Local content

[up-content]
optional

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 pass a template selector, optionally with variables.

[up-fragment]
optional

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

With an [up-fragment] attribute you can omit the [up-target] attribute. 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 pass a template selector, optionally with variables.

[up-document]
optional

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 pass a template selector, optionally with variables.

Customization

[up-mode='modal']
optional

The kind of overlay to open.

Defaults to up.layer.config.mode, which defaults to 'modal'.

See available layer modes.

[up-size='medium']
optional

The size of the overlay.

See overlay sizes for details.

[up-class]
optional

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

See overlay classes.

[up-dismissable]
optional

How the overlay may be dismissed by the user.

See customizing dismiss controls for details.

You may enable multiple dismiss controls by separating values with a space or comma character.

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

Client state

[up-use-data]
optional

The data object object for the overlay's root content element ([up-target]), encoded as relaxed JSON.

If the content element already has an [up-data] attribute, this option will override individual properties from that attribute.

[up-context]
optional

The new overlay's context object, encoded as relaxed JSON.

History

[up-history='auto']
optional

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', fragments 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.

[up-fail-history='auto']
optional

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

See Rendering failed responses differently.

[up-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, set [up-title=false] to explicitly

This attribute is only used when updating history.

[up-location]
optional

An explicit URL to set before rendering.

By default Unpoly will use the link's [href] or the final URL after the server redirected. To prevent the URL from being updated, set [up-location=false].

This attribute is only used when updating history.

[up-meta-tags]
optional

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, set [up-meta-tags=false].

This attribute is only used when updating history.

[up-lang]
optional

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 attrribute from being changed, set [up-lang=false].

This attribute is only used when updating history.

Animation

[up-animation='fade-in']
optional

The name of the opening animation.

[up-easing='ease']
optional

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

[up-duration='175']
optional

The duration of the opening animation in milliseconds.

[up-close-animation='fade-out']
optional

The name of the closing animation.

[up-close-easing='ease']
optional

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

[up-close-duration=175]
optional

The duration of the closing animation in milliseconds.

Close conditions

[up-accept-event]
optional

An event type that will cause this overlay to automatically be accepted when a matching event occurs within the overlay.

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

You may listen to multiple event types by separating types with a space or comma.

See Closing when an event is emitted.

[up-dismiss-event]
optional

An event type that will cause this overlay to automatically be dismissed when a matching event occurs within the overlay.

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

You may listen to multiple event types by separating types with a space or comma.

See Closing when an event is emitted.

[up-accept-location]
optional

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

The overlay result value is an object of named segments matches captured by the URL pattern.

See Closing when a location is reached.

[up-dismiss-location]
optional

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

The overlay result value is an object of named segments matches captured by the URL pattern.

See Closing when a location is reached.

Callbacks

[up-on-opened]
optional

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

The snippet runs in the following scope:

Expression Value
this The link that opened the overlay
layer An up.Layer object for the new overlay
event An up:layer:opened event
[up-on-accepted]
optional

A JavaScript snippet that is called when the overlay was accepted.

The snippet runs in the following scope:

Expression Value
this The link that originally opened the overlay
layer An up.Layer object for the accepted overlay
value The overlay's acceptance value
response The server response that caused the overlay to close
event An up:layer:accepted event
[up-on-dismissed]
optional

A JavaScript snippet that is called when the overlay was dismissed.

The snippet runs in the following scope:

Expression Value
this The link that originally opened the overlay
layer An up.Layer object for the dismissed overlay
value The overlay's dismissal value
response The server response that caused the overlay to close
event An up:layer:dismissed event
[up-confirm]
optional

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

The message will be shown as a native browser prompt.

If the user does not confirm, no request is sent and no fragments are updated.

[up-on-loaded]
optional

A JavaScript snippet that is executed when the server responds with new HTML, but before the HTML is rendered.

The snippet runs in the following scope:

Expression Value
this The link being followed
event A preventable up:fragment:loaded event

The snippet will also run for failed responses.

[up-on-offline]
optional

A JavaScript snippet that is executed when the fragment could not be loaded due to a disconnect or timeout.

Expression Value
this The link being followed
error An up.Offline error
[up-on-rendered]
optional

A JavaScript snippet that is executed when Unpoly has updated fragments.

The snippet runs in the following scope:

Expression Value
this The link being followed
result The up.RenderResult for the respective render pass

The snippet will be called zero, one or two times:

  • When the server rendered an empty response, no fragments are updated. [up-on-rendered] is not called.
  • When the server rendered a matching fragment, it will be updated on the page. [up-on-rendered] is called with the result.
  • When revalidation renders a second time, [up-on-rendered] is called again with the final result.

Also see Running code after rendering.

[up-on-finished]
optional

A JavaScript snippet that is executed when no further DOM changes will be caused by this render pass.

In particular:

Expression Value
this The link being followed
result The up.RenderResult for the last render pass that updated a fragment

If revalidation re-rendered the fragment, result describes updates 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.

Also see Awaiting postprocessing.

[up-on-error]
optional

A JavaScript snippet that is run when any error is thrown during the rendering process.

Expression Value
this The link being followed
error An Error object

The callback is also called when the render pass fails due to network issues, or aborts.

Also see Handling errors.