Edit this page

up.fragment up.render([target], [options])
JavaScript function

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

The current and new elements must both match the same CSS selector. The selector is either given as { target } option, or a main target is used as default.

See the fragment placement selector for many examples for how you can target content.

This function has many options to enable scrolling, focus, request cancelation and other side effects. These options are all disabled by default and must be opted into one-by-one. To enable defaults that a user would expects for navigation (like clicking a link), pass { navigate: true } or use up.navigate() instead.

Passing the new fragment

The new fragment content can be passed as one of the following options:

  • { url } fetches and renders content from the server
  • { document } renders content from a given HTML document string or partial document
  • { fragment } renders content from a given HTML string that only contains the new fragment
  • { content } replaces the targeted fragment's inner HTML with the given HTML string

Example

Let's say your current HTML looks like this:

<div class="one">old one</div>
<div class="two">old two</div>

We now replace the second <div> by targeting its CSS class:

up.render({ target: '.two', url: '/new' })

The server renders a response for /new:

<div class="one">new one</div>
<div class="two">new two</div>

Unpoly looks for the selector .two in the response and implants it into the current page. The current page now looks like this:

<div class="one">old one</div>
<div class="two">new two</div>

Note how only .two has changed. The update for .one was discarded, since it didn't match the selector.

Events

Unpoly will emit events at various stages of the rendering process:

Parameters

[target] stringorElementorjQueryorArray<string> optional

The CSS selector to update.

If omitted a main target will be rendered.

You may also pass a DOM element or jQuery element here, in which case a selector will be inferred from the element attributes. The given element will also be used as { origin } for the fragment update.

You may also pass an array of selector alternatives. The first selector matching in both old and new content will be used.

Instead of passing the target as the first argument, you may also pass it as a ยด{ target }` option..

[options.target] stringorElementorjQueryorArray<string> optional

The CSS selector to update.

See documentation for the target parameter.

[options.fallback=false] stringorboolean optional

Specifies behavior if the target selector is missing from the current page or the server response.

If set to a CSS selector string, Unpoly will attempt to replace that selector instead.

If set to true Unpoly will attempt to replace a main target instead.

If set to false Unpoly will immediately reject the render promise.

[options.navigate=false] boolean optional

Whether this fragment update is considered navigation.

[options.url] string optional

The URL to fetch from the server.

Instead of making a server request, you may also pass an existing HTML string as { document }, { fragment } or { content } option.

[options.method='get'] string optional

The HTTP method to use for the request.

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

[options.params] ObjectorFormDataorstringorArray optional

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.

[options.headers={}] Object optional

An object with additional request headers.

Note that Unpoly will by default send a number of custom request headers. E.g. the X-Up-Target header includes the targeted CSS selector. See up.protocol and up.network.config.requestMetaKeys for details.

[options.content] stringorElement optional

The new inner HTML for the fragment.

[options.fragment] stringorElement optional

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

The { target } selector will be derived from the root element in the given HTML:

// This will update .foo
up.render({ fragment: '<div class=".foo">inner</div>' })

If your HTML string contains other fragments that will not be rendered, use the { document } option instead.

If your HTML string comprises only the new fragment's inner HTML, consider the { content } option.

[options.document] stringorElementorDocument optional

A string of HTML containing the new fragment.

The string may contain other HTML, but only the element matching the { target } selector will be extracted and placed into the page. Other elements will be discarded.

If your HTML string comprises only the new fragment, consider the { fragment } option instead. With { fragment } you don't need to pass a { target }, since Unpoly can derive it from the root element in the given HTML.

If your HTML string comprises only the new fragment's inner HTML, consider the { content } option.

[options.fail='auto'] string optional

How to render a server response with an error code.

Any HTTP status code other than 2xx is considered an error code.

See handling server errors for details.

[options.history] booleanorstring optional

Whether the browser URL and window title will be updated.

If set to true, the history will always be updated, using the title and URL from the server response, or from given { title } and { location } options.

If set to 'auto' history will be updated if the { target } matches a selector in up.fragment.config.autoHistoryTargets. By default this contains all main targets.

If set to false, the history will remain unchanged.

[options.title] string optional

An explicit document title to use after rendering.

By default the title is extracted from the response's <title> tag. You may also pass { title: false } to explicitly prevent the title from being updated.

Note that the browser's window title will only be updated it you also pass a { history } option.

[options.location] string optional

An explicit URL to use after rendering.

By default Unpoly will use the { url } or the final URL after the server redirected. You may also pass { location: false } to explicitly prevent the URL from being updated.

Note that the browser's URL will only be updated it you also pass a { history } option.

[options.transition] string optional

The name of an transition to morph between the old and few fragment.

If you are prepending or appending content, use the { animation } option instead.

[options.animation] string optional

The name of an animation to reveal a new fragment when prepending or appending content.

If you are replacing content (the default), use the { transition } option instead.

[options.duration] number optional

The duration of the transition or animation (in millisconds).

[options.easing] string optional

The timing function that accelerates the transition or animation.

See MDN documentation for a list of available timing functions.

[options.cache] boolean optional

Whether to read from and write to the cache.

With { cache: true } Unpoly will try to re-use a cached response before connecting to the network. If no cached response exists, Unpoly will make a request and cache the server response.

Also see up.request({ cache }).

[options.clearCache] booleanorstring optional

Whether existing cache entries will be cleared with this request.

Defaults to the result of up.network.config.clearCache, which defaults to clearing the entire cache after a non-GET request.

To only uncache some requests, pass an URL pattern that matches requests to uncache. You may also pass a function that accepts an existing up.Request and returns a boolean value.

[options.solo] booleanorstringorFunction(request): boolean optional

With { solo: true } Unpoly will abort all other requests before laoding the new fragment.

To only abort some requests, pass an URL pattern that matches requests to abort. You may also pass a function that accepts an existing up.Request and returns a boolean value.

[options.origin] ElementorjQuery optional

The element that triggered the change.

When multiple elements in the current page match the { target }, Unpoly will replace an element in the origin's vicinity.

The origin's selector will be substituted for :origin in a target selector.

[options.layer='origin current'] stringorup.LayerorElement optional

The layer in which to match and render the fragment.

See layer option for a list of allowed values.

To open the fragment in a new overlay, pass { layer: 'new' }. In this case options for up.layer.open() may also be used.

[options.peel] boolean optional

Whether to close overlays obstructing the updated layer when the fragment is updated.

This is only relevant when updating a layer that is not the frontmost layer.

[options.context] Object optional

An object that will be merged into the context of the current layer once the fragment is rendered.

[options.keep=true] boolean optional

Whether [up-keep] elements will be preserved in the updated fragment.

[options.hungry=true] boolean optional

Whether [up-hungry] elements outside the updated fragment will also be updated.

[options.scroll] booleanorstringorElementorFunction optional

How to scroll after the new fragment was rendered.

See scroll option for a list of allowed values.

[options.saveScroll=true] boolean optional

Whether to save scroll positions before updating the fragment.

Saved scroll positions can later be restored with { scroll: 'restore' }.

[options.focus] booleanorstringorElementorFunction optional

What to focus after the new fragment was rendered.

See focus option for a list of allowed values.

[options.confirm] string optional

A message the user needs to confirm before fragments are updated.

The message will be shown as a native browser prompt.

If the user does not confirm the render promise will reject and no fragments will be updated.

[options.feedback] booleanorElement optional

Whether to give the { origin } element an .up-active class while loading and rendering content.

May also pass an element which should receive the .up-active class.

[options.onLoaded] Function(Event) optional

A callback that will be run when when the server responds with new HTML, but before the HTML is rendered.

The callback argument is a preventable up:fragment:loaded event.

[options.onFinished] Function() optional

A callback that will be run when all animations have concluded and elements were removed from the DOM tree.

Return value

A promise that fulfills when the page has been updated.

If the update is animated, the promise will be resolved before the existing element was removed from the DOM tree. The old element will be marked with the .up-destroying class and removed once the animation finishes. To run code after the old element was removed, pass an { onFinished } callback.

The promise will fulfill with an up.RenderResult that contains references to the updated fragments and layer.

This website uses cookies to improve usability and analyze traffic.
I accept or learn more