Edit this page

up.link [up-defer]
HTML selector

This feature is experimental. It may be changed or removed in a future version.

A placeholder for content that is loaded later from another URL.

By moving expensive but non-critical fragments into partials, you can paint critical content earlier.

See lazy loading content for details.


Identify fragments that are expensive to render on the server, but aren't immediately required. For example, you may have a large navigation menu that only appears once the user clicks a menu icon:

<div id="menu">
  Hundreds of links here

To remove the menu from the initial render pass, extract its contents to its own route, like /menu.

In the initial view, only leave a placeholder element and mark it with an [up-defer] attribute. Also set an [up-href] attribute with the URL from which to load the deferred content:

<div id="menu" up-defer up-href="/menu"> <!-- mark-phrase "up-defer" -->

The placeholder content can show a pending state while the full content is loading.

When the [up-defer] placeholder is rendered, it will immediately make a request to fetch its content from /menu:

GET /path HTTP/1.1
X-Up-Target: #menu


By default the placeholder is targeting itself (#menu). For this the element must have a derivable target selector.

The server is now expected to respond with a page containing #menu with content:

<div id="menu">
  Hundreds of links here

The server is free to send additional elements or even a full HTML document. Only #menu will be updated on the page. Other elements from the response will be discarded.

Modifying attributes


All attributes for a[up-follow] may also be used.

[up-defer='insert'] optional

When to load and render the deferred content.

When set to 'insert' (the default), the deferred content will load immediatedly when the [up-defer] element is inserted into the DOM.

When set to 'reveal', the deferred content will load when the [up-defer] placeholder is scrolled into the viewport. If the element is already visible when inserted, loading will start immediately. Also see loading as the placeholder becomes visible.

When set to 'manual' the deferred content will not load on its own. You can control the load timing by calling up.deferred.load() from your own JavaScripts.

[up-intersect-margin='0'] optional

With [up-defer=reveal], this enlarges the viewport by the given number of pixels before computing the intersection.

A positive number will load the deferred content some pixels before it becomes visible.

A negative number will require the user to scroll some pixels into the element before it is loaded.

[up-href] optional

The URL from which to load the deferred content.

If your [up-defer] placeholder is a standard hyperlink, you can use an [href] attribute instead.

[up-headers] optional

A JSON object with additional request headers.

[up-cache='auto'] optional

Whether to cache the deferred content.

[up-target=':origin'] optional

A selector for the fragment to render the content in.

By default the [up-defer] element itself will be replaced with the loaded content. For this the element must have a derivable target selector.

You may target one or multiple fragments. To target the placeholder itself, you can use :origin target instead of spelling out a selector.

[up-feedback='true'] optional

Whether the [up-defer] placeholder is assigned an .up-active class while loading its content.

[up-background='false'] optional

Whether to load the deferred content in the background.

Background requests will not show loading indicators.