Edit this page

API Attributes and options

Unpoly attributes

Unpoly provides up-prefixed attributes that enable additional behavior on HTML elements. For example, the [up-follow] attribute will cause a clicked link to swap the <main> or <body> element instead of replacing the full page:

<a href="/path" up-follow>Click me</a> <!-- mark-phrase "up-follow" -->

Modifying attributes

Most Unpoly attributes have modifying attributes to fine-tune their behavior. For example, the [up-transition] attribute causes an [up-follow] to swap using an animated transition:

<a href="/path" up-follow up-transition="cross-fade">Click me</a> <!-- mark-phrase "up-transition" -->

Modifying attributes are documented with the main attribute they're modifying. For example, see modifying attributes for [up-follow].

Configuring default behavior for all elements

Instead of configuring the same attributes on many elements, you can configure Unpoly to apply behavior to all elements matching a given CSS selector.

For example, the following configuration will enable single-page navigation for all hyperlinks:

up.link.config.followSelectors.push('a[href]')

Unpoly will now handle all links, even those without an [up-follow] attribute:

<a href="/path">Click for single-page navigation</a>

Tip

An alternative way to apply default behavior to many elements is a macro.

Making exceptions

You can still make exceptions by setting an [up-follow=false] attribute:

<a href="/path" up-follow="false">Click for full page load</a> <!-- mark-phrase "false" -->

Overriding attributes with JavaScript options

Most Unpoly attributes come with matching JavaScript functions that trigger the same behavior programmatically.

Let's say you have the following link:

<a href="/path" up-follow up-meta-tags="false">Click me</a>

Your scripts can tell Unpoly to follow the link like this:

up.follow(link)

The up.follow() call will parse all modifying attributes from the given link element into a JavaScript object with camel-cased keys. So we're implicitly making the following call:

// The options object is parsed from the link and can be omitted
up.follow(link, { url: '/path', metaTags: false })

If you pass other options, these will override any options parsed from the link's attributes:

// This overrides the [up-meta-tags=false] attribute
up.follow(link, { metaTags: true })

Auto-attributes

Some attributes default to a value "auto". This indicates a more complex default.

For example, the [up-cache=auto] attribute caches all links with a GET method:

<a href="/path" up-follow up-cache="auto">Click me</a> <!-- mark-phrase "auto" -->

You can usually configure auto-behavior. For example, the following will prevent auto-caching of requests to URLs ending with /edit:

let defaultAutoCache = up.network.config.autoCache
up.network.config.autoCache = function(request) {
  defaultAutoCache(request) && !request.url.endsWith('/edit')
}

Boolean attributes

Most Unpoly attributes can be enabled with a value "true" and be disabled with a value "false":

<a href="/path" up-follow="true">Click for single-page navigation</a> <!-- mark-phrase "true" -->
<a href="/path" up-follow="false">Click for full page load</a> <!-- mark-phrase "false" -->

Instead of setting a true you can also set an empty value:

<a href="/path" up-follow>Click for single-page navigation</a>
<a href="/path" up-follow="">Click for single-page navigation</a>
<a href="/path" up-follow="true">Click for single-page navigation</a>

Boolean values can be helpful with a server-side templating language like ERB, Liquid or Haml, when the attribute value is set from a boolean variable:

<a href="/path" up-follow="<%= is_signed_in %>">Click me</a> <%# mark-phrase "is_signed_in" %>

This can also help when you're generating HTML from a different programming language and want to pass a true literal as an attribute value:

link_to 'Click me', '/path', 'up-follow': true