Edit this page

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

Opens a new overlay.

Opening a layer is considered navigation by default.

Example

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

Parameters

[options] Object optional

All render options may be used.

You may configure default layer attributes in up.layer.config.

[options.target] string optional

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

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

If the { target } option 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.

[options.url] string optional

The URL to fetch from the server.

Unpoly will select the given { target } from the server response and place a matching element inside the overlay container. See loading content from a URL.

Instead of making a server request, you may also render an existing string of HTML using the { content }, { fragment } or { document } options.

[options.content] string|Element|List<Node> optional

The inner HTML for the overlay container.

The given content will be wrapped in an element matching the given { target }. If no target is given, a wrapper matching a main target will be used.

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

[options.fragment] string|Element optional

A string of HTML comprising only outer HTML to place inside the overlay container.

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.

[options.document] string|Element|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 refer to a template.

[options.layer="new"] string optional

Whether to stack the new overlay or replace existing overlays.

See replacing existing overlays.

[options.mode] string optional

The kind of overlay to open.

See available layer modes.

[options.size] string optional

The size of the overlay.

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

[options.class] string optional

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

See overlay classes.

[options.dismissable=true] boolean|string|Array<string> optional

How the overlay may be dismissed by the user.

Supported values are 'key', 'outside' and 'button'. See customizing dismiss controls for details.

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

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

[options.history] boolean|string 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.

[options.trapFocus] boolean optional

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

By default focus is trapped for all overlays except popups.

[options.animation] string|Function optional

The opening animation.

[options.origin] Element optional

The link element that caused this overlay to open.

The origin will be re-focused when the overlay closes.

[options.onOpened] Function(Event) optional

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.

[options.onAccepted] Function(Event) optional

A function that is called when the overlay was accepted.

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

[options.onDismissed] Function(Event) optional

A function that is called when the overlay was dismissed.

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

[options.acceptEvent] string|Array<string> optional

One or more event types 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.

See Closing when an event is emitted.

[options.dismissEvent] string|Array<string> optional

One or more event types 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.

See Closing when an event is emitted.

[options.acceptLocation] string|Array<string> optional

One or more 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.

[options.dismissLocation] string|Array<string> optional

One or more 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.

[options.context={}] Object optional experimental

The initial context object for the new overlay.

[options.position] string optional

The position of the popup relative to the { origin } element that opened the overlay.

Supported values are 'top', 'right', 'bottom' and 'left'.

See popup position.

[options.align] string optional

The alignment of the popup within its { position }.

Supported values are 'top', 'right', 'center', 'bottom' and 'left'.

See popup position.

Return value

A promise for the up.Layer object that models the new overlay.

The promise will be resolved once the overlay was placed into the DOM.