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

# `up.fragment`

The JavaScript API to render, look up and destroy page fragments. Every link, form, overlay or poll that Unpoly handles ends in [`up.render()`](https://unpoly.com/api/up.render.md), and your own code can call it with the same options.

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

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

<nav aria-label="Guides">

- [Learn: Advanced rendering](https://unpoly.com/learn/advanced-rendering.md)

</nav>

---

## Features {#features}

- ### [:layer](https://unpoly.com/api/layer.md) (Target selector)

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

- ### [:main](https://unpoly.com/api/main.md) (Target selector)

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

- ### [:maybe](https://unpoly.com/api/maybe.md) (Target selector)

  Marks a target selector as optional.

- ### [:none](https://unpoly.com/api/none.md) (Target selector)

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

- ### [:origin](https://unpoly.com/api/origin.md) (Target selector)

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

- ### [up.context](https://unpoly.com/api/up.context.md) (JavaScript property) (experimental)

  Returns the current context.

- ### [up.destroy(element, [options])](https://unpoly.com/api/up.destroy.md) (JavaScript function)

  Destroys the given element or selector.

- ### [.up-destroying](https://unpoly.com/api/up-destroying.md) (CSS class)

  Elements are assigned the `.up-destroying` class before they are destroyed or while they are being removed by a transition.

- ### [[up-etag]](https://unpoly.com/api/up-etag.md) (HTML attribute)

  Sets an ETag for the fragment's underlying data.

- ### [up.extract(target, html, [options])](https://unpoly.com/api/up.extract.md) (JavaScript function) (deprecated)

  Updates a selector on the current page with the same selector from the given HTML string.

- ### [up.fragment.abort([element], [options])](https://unpoly.com/api/up.fragment.abort.md) (JavaScript function)

  Aborts requests targeting a fragment or layer.

- ### [up:fragment:aborted](https://unpoly.com/api/up:fragment:aborted.md) (DOM event)

  This event is emitted when requests for an element were aborted.

- ### [up.fragment.all([root], selector, [options])](https://unpoly.com/api/up.fragment.all.md) (JavaScript function)

  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)](https://unpoly.com/api/up.fragment.closest.md) (JavaScript function)

  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](https://unpoly.com/api/up.fragment.config.md) (Configuration object)

  Configures defaults for fragment updates.

- ### [up.fragment.contains(root, query)](https://unpoly.com/api/up.fragment.contains.md) (JavaScript function) (experimental)

  Returns whether the given `root` matches or contains the given selector or element.

- ### [up:fragment:destroyed](https://unpoly.com/api/up:fragment:destroyed.md) (DOM event)

  This event is emitted after a page fragment was destroyed and removed from the DOM.

- ### [up.fragment.etag(element)](https://unpoly.com/api/up.fragment.etag.md) (JavaScript function)

  Returns the ETag of the content in the given element.

- ### [up.fragment.first([root], selector, [options])](https://unpoly.com/api/up.fragment.first.md) (JavaScript function) (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])](https://unpoly.com/api/up.fragment.get.md) (JavaScript function)

  Returns the first fragment matching the given CSS selector.

- ### [up:fragment:inserted](https://unpoly.com/api/up:fragment:inserted.md) (DOM event)

  When a page fragment has been inserted or updated, this event is emitted on the new element.

- ### [up.fragment.isAlive(fragment)](https://unpoly.com/api/up.fragment.isAlive.md) (JavaScript function) (experimental)

  Returns whether the given fragment is both attached to the DOM and not currently in a destroy animation.

- ### [up.fragment.isTargetable(element, [options])](https://unpoly.com/api/up.fragment.isTargetable.md) (JavaScript function)

  Returns whether Unpoly can derive a target selector for the given element.

- ### [up:fragment:keep](https://unpoly.com/api/up:fragment:keep.md) (DOM event)

  This event is emitted before an existing element is kept during a render pass.

- ### [up:fragment:kept](https://unpoly.com/api/up:fragment:kept.md) (DOM event) (experimental)

  The `up:fragment:kept` event is emitted _after_ an existing element has been kept during a render pass.

- ### [up:fragment:loaded](https://unpoly.com/api/up:fragment:loaded.md) (DOM 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])](https://unpoly.com/api/up.fragment.matches.md) (JavaScript function)

  Returns whether the given element matches the given CSS selector or other element.

- ### [up:fragment:offline](https://unpoly.com/api/up:fragment:offline.md) (DOM event)

  This event is emitted when the device loses its network connection while rendering content.

- ### [up.fragment.onAborted(element, callback)](https://unpoly.com/api/up.fragment.onAborted.md) (JavaScript function) (experimental)

  Runs a callback when the given element _or its ancestors in the same layer_ were aborted.

- ### [up.fragment.onKept(element, callback)](https://unpoly.com/api/up.fragment.onKept.md) (JavaScript function) (experimental)

  Runs a callback when the given element _or its ancestors in the same layer_ were kept.

- ### [up.fragment.source(element)](https://unpoly.com/api/up.fragment.source.md) (JavaScript function)

  Returns the URL from which the given element was loaded.

- ### [up.fragment.subtree(root, selector)](https://unpoly.com/api/up.fragment.subtree.md) (JavaScript function)

  Returns a list of a `root` element's descendants matching the given selector.

- ### [up.fragment.time(element)](https://unpoly.com/api/up.fragment.time.md) (JavaScript function)

  Returns the last modification time of the content in the given element.

- ### [up.fragment.toTarget(element, [options])](https://unpoly.com/api/up.fragment.toTarget.md) (JavaScript function)

  Derives a CSS selector that matches the given element as good as possible.

- ### [[up-id]](https://unpoly.com/api/up-id.md) (HTML attribute)

  Sets a unique identifier for this element.

- ### [[up-keep]](https://unpoly.com/api/up-keep.md) (HTML attribute)

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

- ### [[up-main]](https://unpoly.com/api/up-main.md) (HTML attribute)

  Marks this element as the main fragment of your application layout.

- ### [up.navigate([target], [options])](https://unpoly.com/api/up.navigate.md) (JavaScript function)

  Navigates to the given URL by updating a major fragment in the current page.

- ### [up.reload([element], [options])](https://unpoly.com/api/up.reload.md) (JavaScript function)

  Replaces the given element with a fresh copy fetched from the server.

- ### [up.render([target], [options])](https://unpoly.com/api/up.render.md) (JavaScript function)

  Replaces elements on the current page with matching elements from a server response or HTML string.

- ### [up.replace(target, url, [options])](https://unpoly.com/api/up.replace.md) (JavaScript function) (deprecated)

  Replaces elements on the current page with corresponding elements from a new page fetched from the server.

- ### [[up-source]](https://unpoly.com/api/up-source.md) (HTML attribute)

  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])](https://unpoly.com/api/up.template.clone.md) (JavaScript function)

  Clones a template element.

- ### [up:template:clone](https://unpoly.com/api/up:template:clone.md) (DOM event)

  This event is emitted before a template is cloned.

- ### [[up-time]](https://unpoly.com/api/up-time.md) (HTML attribute)

  Sets the time when the fragment's underlying data was last changed.

- ### [up.visit(url, [options])](https://unpoly.com/api/up.visit.md) (JavaScript function)

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