`up.fragment`

JavaScript namespace

The JavaScript API to render, look up and destroy page fragments. Every link, form, overlay or poll that Unpoly handles ends in up.render(), and your own code can call it with the same options.

up.render() replaces elements on the current page with matching elements from a server response or an HTML string. up.navigate() does the same with the defaults of a user navigation, like updating history and scrolling to the new content. up.reload() fetches a fresh copy of a fragment from the URL it was loaded from, and up.destroy() removes a fragment, with an optional animation.

Lookup functions like up.fragment.get() differ from document.querySelector(): they only see the current layer, ignore elements that are playing out their exit animation, and understand Unpoly's own selectors like :main or :origin. Elements marked [up-keep] are kept across updates. For low-level DOM utilities that complement the browser's native API, see up.element.

Learn: Advanced rendering

Features

:layer TARGET

Your target selectors may use this pseudo-selector to replace the layer's topmost swappable element.
:main TARGET

A pseudo-selector that matches the layer's main fragment.
:maybe TARGET

Marks a target selector as optional.
:none TARGET

To make a server request without changing a fragment, use the :none target.
:origin TARGET

Your target selectors may use this pseudo-selector to reference the origin element that triggered the change.
up.context JS experimental

Returns the current context.
up.destroy(element, [options]) JS

Destroys the given element or selector.
.up-destroying CSS

Elements are assigned the .up-destroying class before they are destroyed or while they are being removed by a transition.
[up-etag] ATTR

Sets an ETag for the fragment's underlying data.
up.extract(target, html, [options]) JS deprecated

Updates a selector on the current page with the same selector from the given HTML string.
up.fragment.abort([element], [options]) JS

Aborts requests targeting a fragment or layer.
up:fragment:aborted EVENT

This event is emitted when requests for an element were aborted.
up.fragment.all([root], selector, [options]) JS

Returns all elements matching the given CSS selector, but ignores elements that are being destroyed or that are being removed by a transition.
up.fragment.closest(element, selector) JS

Returns the first element that matches the selector by testing the element itself and traversing up through ancestors in element's layers.
up.fragment.config CONFIG

Configures defaults for fragment updates.
up.fragment.contains(root, query) JS experimental

Returns whether the given root matches or contains the given selector or element.
up:fragment:destroyed EVENT

This event is emitted after a page fragment was destroyed and removed from the DOM.
up.fragment.etag(element) JS

Returns the ETag of the content in the given element.
up.fragment.first([root], selector, [options]) JS deprecated

Returns the first element matching the given selector, but ignores elements that are being destroyed or that are being removed by a transition.
up.fragment.get([root], selector, [options]) JS

Returns the first fragment matching the given CSS selector.
up:fragment:inserted EVENT

When a page fragment has been inserted or updated, this event is emitted on the new element.
up.fragment.isAlive(fragment) JS experimental

Returns whether the given fragment is both attached to the DOM and not currently in a destroy animation.
up.fragment.isTargetable(element, [options]) JS

Returns whether Unpoly can derive a target selector for the given element.
up:fragment:keep EVENT

This event is emitted before an existing element is kept during a render pass.
up:fragment:kept EVENT experimental

The up:fragment:kept event is emitted after an existing element has been kept during a render pass.
up:fragment:loaded EVENT

This event is emitted after the server response was loaded, but before the HTML is used to change a fragment.
up.fragment.matches(fragment, selector, [options]) JS

Returns whether the given element matches the given CSS selector or other element.
up:fragment:offline EVENT

This event is emitted when the device loses its network connection while rendering content.
up.fragment.onAborted(element, callback) JS experimental

Runs a callback when the given element or its ancestors in the same layer were aborted.
up.fragment.onKept(element, callback) JS experimental

Runs a callback when the given element or its ancestors in the same layer were kept.
up.fragment.source(element) JS

Returns the URL from which the given element was loaded.
up.fragment.subtree(root, selector) JS

Returns a list of a root element's descendants matching the given selector.
up.fragment.time(element) JS

Returns the last modification time of the content in the given element.
up.fragment.toTarget(element, [options]) JS

Derives a CSS selector that matches the given element as good as possible.
[up-id] ATTR

Sets a unique identifier for this element.
[up-keep] ATTR

Elements with an [up-keep] attribute will be kept when rendering.
[up-main] ATTR

Marks this element as the main fragment of your application layout.
up.navigate([target], [options]) JS

Navigates to the given URL by updating a major fragment in the current page.
up.reload([element], [options]) JS

Replaces the given element with a fresh copy fetched from the server.
up.render([target], [options]) JS

Replaces elements on the current page with matching elements from a server response or HTML string.
up.replace(target, url, [options]) JS deprecated

Replaces elements on the current page with corresponding elements from a new page fetched from the server.
[up-source] ATTR

When Unpoly inserts a fragment, the [up-source] attribute is automatically set to the URL from which the fragment's HTML was loaded.
up.template.clone(template, [data], [options]) JS

Clones a template element.
up:template:clone EVENT

This event is emitted before a template is cloned.
[up-time] ATTR

Sets the time when the fragment's underlying data was last changed.
up.visit(url, [options]) JS

Fetches the given URL with JavaScript and replaces the current layer's main fragment with a matching fragment from the server response.