3.15
Search docs… /
Menu
Skill

Learn Following links

Any link can update a fragment of the current page, instead of loading a full new document. When Unpoly handles a link's click this way, we say the link is followed.

To have Unpoly handle a link, set an [up-follow] attribute:

<a href="/posts/5" up-follow>Read post</a> <!-- mark: up-follow -->

When the user clicks, Unpoly requests /posts/5. The server responds with a full HTML page, the same way it would for any browser request. Unpoly extracts the response's main fragment and replaces the main fragment on the current page. Elements outside the updated fragment keep their state, like unsaved input in other forms.

The link remains a standard hyperlink. When the user opens it in a new tab, or when JavaScript is unavailable, the browser loads the destination as a full page.

Tip

Instead of annotating individual links, you can also configure Unpoly to follow all links on the page.

Updating a specific fragment

To update an element other than the main fragment, set an [up-target] attribute with a CSS selector:

<a href="/posts/5" up-target=".content">Read post</a> <!-- mark: up-target=".content" -->

<div class="content">
  Old content
</div>

Unpoly finds the .content element in the server response and swaps it into the current page.

An [up-target] attribute already implies [up-follow], so you don't need to set both. The same goes for other rendering attributes like [up-layer] or [up-transition].

A target can also address multiple fragments, append to an existing element, or resolve relative to the clicked link. See Targeting fragments for everything a target selector can express.

Following a link is considered navigation by default. When a link updates the layer's main fragment, Unpoly behaves like a full page load would: the browser URL and history are updated, and the page scrolls to the top. Focus moves to the new fragment.

See Navigation defaults for all navigation defaults and how to customize them.

Acting on press

A standard link activates on click, when the mouse button is released. Set an [up-instant] attribute to act on mousedown instead:

<a href="/users" up-follow up-instant>User list</a> <!-- mark: up-instant -->

This saves the time the user takes to release the mouse button. Because the request is sent that much earlier, the interaction feels faster.

Users can still activate an instant link with the keyboard. They can no longer cancel a click by dragging the pressed mouse away from the link, so reserve [up-instant] for navigation, where a stray click has no severe effect. See [up-instant] for details.

Links that are never followed

Some links are always handled by the browser, even when they match an [up-follow] selector:

  • Links with an [up-follow=false] attribute. Also see boolean attributes.
  • Links with a [download] attribute.
  • Links with a [target] attribute (to target an iframe or open new browser tab).
  • Links with a javascript:, mailto: or tel: scheme.
  • Links with a cross-origin [href].
  • Links with an [href] that only contains a #hash (like # or #section) and don't also have local HTML in an [up-document], [up-fragment], or [up-content] attribute.
  • Any additional exceptions configured in up.link.config.noFollowSelectors.

Clicking such a link falls back to default browser behavior.

Following links from JavaScript

To follow a link element programmatically, pass it to up.follow():

let link = document.querySelector('a.featured')
up.follow(link)

The link's [up-...] attributes are honored, as if the user had clicked the link. You can pass additional render options to supplement or override the link's attributes:

up.follow(link, { target: '.sidebar' })

To update fragments without a link element, use up.render().