Edit this page

API Preloading links

You can preload links in advance. When a preloaded link is clicked the response will already be cached, making the interaction feel instant.

Eager preloading may also be used to populate the cache and keep links accessible while offline.

Preloading on hover

To preload a link when the user hovers over it, set an [up-preload] attribute:

<a href="/path" up-preload>Hover over me to preload my content</a>

By default Unpoly will wait for 90 milliseconds of hovering before making the preload request. This prevents accidental preloading when mouse moves over the link with no intention to click it.

The delay can be controlled by setting an [up-preload-delay] attribute or configuring up.link.config.preloadDelay. Increasing the delay will lower the load in your server, but will also make the interaction feel less instant.

On touch devices preloading will begin when the user places her finger on the link.

To preload all links on hover, configure up.link.config.preloadSelectors.

Eager preloading on insertion

To preload a link as soon as it appears in the DOM, set an [up-preload="insert"] attribute.

This is useful for links with a high probability of being clicked, like a navigation menu:

<a href="/menu" up-layer="new drawer" up-preload="insert">≡ Menu</a> <!-- mark-phrase "insert" -->

When an eagerly preloaded fragment is rendered multiple times, only a single request is made. All subsequent render passes will render from the cache.

Preloading when a link scrolls into view

To "lazy preload" a link when it is scrolled into the viewport, set an [up-preload="reveal"] attribute.

This is useful when an element is below the fold and is unlikely to be clicked until the the user scrolls:

<a href="/stories/106" up-preload="reveal">Full story</a> <!-- mark-phrase "reveal" -->

When a lazy preloading link enters and exit its viewport repeatedly, only a single request is made.

Custom preload timing

To programmatically preload any link element at a time of your choosing, use the up.link.preload() function.

The following compiler would preload a link with a [rel=next] attribute 500 milliseconds after it was inserted:

up.compiler('link[rel=next]', (link) => {
  setTimeout(() => up.link.preload(link), 500)

A link that is preloaded in that fashion does not require an [up-preload] attribute.

Preloading a URL

To preload a given URL without a link element, you can make a background request that caches:

up.request('/menu', { cache: true, background: true })

Preload request behavior

Requests sent when preloading behave somewhat different to requests sent when following a link directly:

  • Preloading will not change elements ("render").
  • Preloading a link will not abort pending requests targeting the same fragments. Only when the link is clicked later conflicting requests are aborted.
  • Preload requests are considered background requests and will not show the progress bar.
  • Preloaded content is placed into the cache automatically.
  • When a link destination is already cached, preloading will not make another request, even if the cache entry is expired. When the link is clicked and the cached content is rendered into page, the fragment will be revalidated if the cache entry is expired.


When a link is preloaded via the [up-preload] attribute or up.link.preload() function, an up:link:preload event is emitted.

The event can be prevented to stop the preload from taking place:

function isSlowConnection() {
  // https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation
  return navigator.connection && navigator.connection.effectiveType.include('2g')  

up.on('up:link:preload', function(event) {
  if (isSlowConnection()) {