Edit this page

API Linking to fragments
module up.link

The up.link module lets you build links that update fragments instead of entire pages.


In a traditional web application, the entire page is destroyed and re-created when the user follows a link:

Traditional page flow

This makes for an unfriendly experience:

  • State changes caused by AJAX updates get lost during the page transition.
  • Unsaved form changes get lost during the page transition.
  • The JavaScript VM is reset during the page transition.
  • If the page layout is composed from multiple scrollable containers (e.g. a pane view), the scroll positions get lost during the page transition.
  • The user sees a "flash" as the browser loads and renders the new page, even if large portions of the old and new page are the same (navigation, layout, etc.).

Unpoly fixes this by letting you annotate links with an [up-target] attribute. The value of this attribute is a CSS selector that indicates which page fragment to update. The server still renders full HTML pages, but we only use the targeted fragments and discard the rest:

Unpoly page flow

With this model, following links feels smooth. All DOM state outside the updated fragment is preserved. Pages also load much faster since the DOM, CSS and JavaScript environments do not need to be destroyed and recreated for every request.


Let's say we are rendering three pages with a tabbed navigation to switch between screens:

Your HTML could look like this:

  <a href="/pages/a">A</a>
  <a href="/pages/b">B</a>
  <a href="/pages/b">C</a>

  Page A

Since we only want to update the <article> tag, we annotate the links with an up-target attribute:

  <a href="/pages/a" up-target="article">A</a>
  <a href="/pages/b" up-target="article">B</a>
  <a href="/pages/b" up-target="article">C</a>


Instead of article you can use any other CSS selector like #main .article.

With these [up-target] annotations Unpoly only updates the targeted part of the screen. The JavaScript environment will persist and the user will not see a white flash while the new page is loading.




All features

a[up-dash] deprecated

Follows this link as fast as possible.

a[up-follow] stable

Follows this link with JavaScript and updates a fragment with the server response.

a[up-instant] stable

Follows this link on mousedown instead of click.

a[up-preload] stable

Preloads this link before the user clicks it. When the link is clicked, the response will already be cached, making the interaction feel instant.

up:click stable

A click event that honors the [up-instant] attribute.

[up-clickable] experimental

Enables keyboard interaction for elements that represent links or buttons.

[up-defer] experimental

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

up.deferred.load(placeholder, [options]) experimental

Loads a [up-defer="manual"] placeholder.

up:deferred:load experimental

This event is emitted before an [up-defer] placeholder loads its deferred content.

[up-expand] stable

Add an [up-expand] attribute to any element to enlarge the click area of a descendant link.

up.follow(link, [options]) stable

Follows the given link with JavaScript and updates a fragment with the server response.

[up-href] stable

Makes any element behave like a hyperlink.

up.link.config stable

Configures defaults for link handling.

up:link:follow stable

This event is emitted when a link is followed through Unpoly.

up.link.followOptions(link, [options]) stable

Parses the render options that would be used to follow the given link, but does not render.

up.link.isFollowable(link) stable

Returns whether the given link will be followed by Unpoly instead of making a full page load.

up.link.isSafe(link) stable

Returns whether the given link has a safe HTTP method like GET.

up.link.makeFollowable(link) experimental

Makes sure that the given link will be followed by Unpoly instead of making a full page load.

up.link.preload(link, options, [options]) stable

Preloads the given link.

up:link:preload stable

This event is emitted before a link is preloaded.