Edit this page

up.link up.follow(link, [options])
JavaScript function

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

By default the layer's main element will be replaced. Attributes like [up-target] or [up-layer] will be honored.

Following a link is considered navigation by default.

Emits the event up:link:follow.

Examples

Assume we have a link with an [up-target] attribute:

<a href="/users" up-target=".main">Users</a>

Calling up.follow() with this link will replace the page's .main fragment as if the user had clicked on the link:

var link = document.querySelector('a')
up.follow(link)

General

[options]
optional

Render options that should be used for following the link.

Unpoly will parse render options from the given link's attributes. E.g. the [up-target] attribute will be parsed into a { target } option. See [up-follow] for a list of supported attributes.

You may pass this additional options object to supplement or override options parsed from the link attributes.

Targeting

[options.target]
optional

The target selector to update after a successful response.

If omitted, a main target will be rendered.

You may also pass a DOM element or jQuery element here, in which case a selector will be derived. The given element will also be used as { origin } for the fragment update.

You may also pass an array of selector alternatives. The first selector matching in both old and new content will be used.

stringElementjQueryArray<string>
[options.failTarget]
optional

The target selector to update when the server responds with an error code.

See Rendering failed responses differently.

stringElementjQueryArray<string>
[options.fallback]
optional

Specifies behavior if the target selector is missing from the current page or the server response.

If set to a CSS selector string, Unpoly will attempt to replace that selector instead.

If set to true, Unpoly will attempt to replace a main target instead.

If set to false, Unpoly will immediately reject the render promise.

Also see Dealing with missing targets.

stringboolean
[options.match='region']
optional

Controls which fragment to update when the { target } selector yields multiple results.

When set to 'region', Unpoly will prefer to update fragments in the region of the origin element.

If set to 'first', Unpoly will always update the first matching fragment.

Defaults to up.fragment.config.match, which defaults to 'region'.

string
[options.origin]
optional

The element that triggered the change.

When multiple elements in the current page match the { target }, Unpoly will replace an element in the origin's proximity.

The origin's selector will be substituted for :origin in a target selector.

[options.hungry=true]
optional

Whether [up-hungry] elements outside the updated fragment will also be updated.

boolean

Navigation

[options.navigate=true]
optional

Whether this fragment update is considered navigation.

Setting this to true will enable many side effects, like like updating history or scrolling.

Setting this to false will disable most defaults, allowing you to opt into individual side effects using the options below.

boolean

Request

[options.url]
optional

The URL to request from the server.

See loading content from a URL.

string
[options.method='get']
optional

The HTTP method to use for the request.

Common values are 'get', 'post', 'put', 'patch' and 'delete'. The value is case insensitive.

string
[options.params]
optional

Additional parameters that should be sent as the request's query string or payload.

When making a GET request to a URL with a query string, the given { params } will be added to the query parameters.

[options.headers={}]
optional

An object with additional request headers.

Unpoly will by default send a number of custom request headers. E.g. the X-Up-Target header includes the targeted CSS selector. See up.protocol for details.

[options.abort='target']
optional

Whether to abort existing requests before rendering.

See aborting requests for details and a list of options.

booleanstringFunction(request): boolean
[options.abortable=true]
optional

Whether the request may be aborted by other requests targeting the same fragments or layer.

See Aborting rules in layers.

boolean
[options.background=false]
optional

Whether this request will load in the background.

Background requests deprioritized over foreground requests. Background requests also won't emit up:network:late events and won't trigger the progress bar.

boolean
[options.lateDelay]
optional

The number of milliseconds after which this request can cause an up:network:late event and show the progress bar.

To prevent the event and progress bar, pass { lateDelay: false }.

Defaults to up.network.config.lateDelay.

numberboolean
[options.timeout]
optional

The number of milliseconds after which this request fails with a timeout.

Defaults to up.network.config.timeout.

number
[options.fail]
optional

Whether to render failed responses differently.

Failed responses will be rendered using options prefixed with fail, e.g. { failTarget }.

By default any HTTP status code other than 2xx or 304 is considered failed. Pass { fail: false } to handle any response as successful, even with a 4xx or 5xx status code.

booleanFunction(up.Response): boolean

Local content

[options.content]
optional

The new inner HTML for the targeted fragment.

See Updating an element's inner HTML from a string.

Instead of passing an HTML string you can also refer to a template.

stringElementList<Node>
[options.fragment]
optional

A string of HTML comprising only the new fragment's outer HTML.

When passing { fragment } you can omit the { target } option. The target will be derived from the root element in the given HTML.

See Rendering a string that only contains the fragment.

Instead of passing an HTML string you can also refer to a template.

stringElement
[options.document]
optional

A string of HTML containing the targeted fragment.

See Extracting an element's outer HTML from a larger HTML string.

Instead of passing an HTML string you can also refer to a template.

stringElementDocument
[options.response]
optional

An up.Response object that contains the targeted fragments in its text.

See Rendering an up.Response object.

Layer

[options.layer='origin, current']
optional

The layer in which to match and render the fragment.

See layer option for a list of allowed values.

To open the fragment in a new overlay, pass { layer: 'new' }. In this case options for up.layer.open() may also be used.

[options.failLayer='origin, current']
optional

The layer in which render if the server responds with an error code.

See Rendering failed responses differently.

[options.peel]
optional

Whether to close overlays obstructing the updated layer when the fragment is updated.

This is only relevant when updating a layer that is not the frontmost layer.

boolean

History

[options.history]
optional

Whether the browser URL, window title and meta tags will be updated.

If set to true, the history will always be updated.

If set to 'auto' history will be updated if the { target } matches a selector in up.fragment.config.autoHistoryTargets. By default this contains all main targets.

If set to false, the history will remain unchanged.

See Updating history.

booleanstring
[options.failHistory]
optional

Whether to update history when the server responds with an error code.

See Rendering failed responses differently.

booleanstring
[options.title]
optional

An explicit document title to set before rendering.

By default the title is extracted from the response's <title> tag. To prevent the title from being updated, pass { title: false }

This option is only used when updating history.

booleanstring
[options.location]
optional

An explicit browser location URL to set before rendering.

By default Unpoly will use the { url } or the final URL after the server redirected. To prevent the URL from being updated, pass { location: false }.

This option is only used when updating history.

booleanstring
[options.metaTags]
optional

Whether to update meta tags in the <head>.

By default Unpoly will extract meta tags from the response's <head>. To prevent meta tags from being updated, pass { metaTags: false }.

This option is only used when updating history.

booleanArray<Element>
[options.lang]
optional

An explicit language code to set as the html[lang] attribute.

By default Unpoly will extract the language from the response and update the html[lang] attribute in the current page. To prevent the attrribute from being changed, pass { lang: false }.

This option is only used when updating history.

booleanArray<Element>

Animation

[options.transition]
optional

The name of an transition to morph between the old and few fragment.

If you are prepending or appending content, use the { animation } option instead.

string
[options.animation]
optional

The name of an animation to reveal a new fragment when prepending or appending content.

If you are swapping a fragment (the default), use the { transition } option instead.

string
[options.duration]
optional

The duration of the transition or animation (in millisconds).

number
[options.easing]
optional

The timing function that accelerates the transition or animation.

See MDN documentation for a list of available timing functions.

string

Caching

[options.cache]
optional

Whether to read from and write to the cache.

With { cache: true } Unpoly will try to re-use a cached response before connecting to the network. To prevent display of stale content, cached responses are reloaded once rendered. If no cached response exists, Unpoly will make a request and cache the server response.

With { cache: 'auto' } Unpoly will use the cache only if up.network.config.autoCache returns true for the request.

With { cache: false } Unpoly will always make a network request.

boolean
[options.revalidate]
optional

Whether to reload the targeted fragment after it was rendered from a cached response.

With { revalidate: 'auto' } Unpoly will revalidate expired responses.
This behavior can be configured with up.fragment.config.autoRevalidate(response).

With { revalidate: true } Unpoly will always revalidate cached content, regardless of its age.

With { revalidate: false } Unpoly will never revalidate cached content.

booleanstring
[options.revalidatePreview]
optional

A preview that that runs while revalidating cached content.

stringFunction(up.Preview)
[options.expireCache]
optional

Whether existing cache entries will be expired with this request.

Expired content remains in the cache, but will be revalidated with the server after rendering.

By default, any non-GET request will expire the entire cache. This can be configured with up.network.config.expireCache.

To only expire some requests, pass an URL pattern that matches requests to uncache. You may also pass a function that accepts an existing up.Request and returns a boolean value.

booleanstring
[options.evictCache]
optional

Whether existing cache entries will be evicted with this request.

By default, Unpoly will never evict entries while the cache has space, preferring expiration instead. This can be configured with up.network.config.evictCache.

To only evict some requests, pass an URL pattern that matches requests to uncache. You may also pass a function that accepts an existing up.Request and returns a boolean value.

booleanstring

Scrolling

[options.scroll]
optional

How to scroll after the new fragment was rendered.

See scrolling for a list of allowed values.

booleanstringElementFunction
[options.failScroll]
optional

How to scroll after the new fragment was rendered from a failed response.

See Rendering failed responses differently.

booleanstringElementFunction
[options.scrollBehavior='instant']
optional
string
[options.revealSnap]
optional

When to snap to the top when scrolling to an element near the top edge of the viewport's scroll buffer.

number
[options.revealTop]
optional

When to move a revealed element to the top when scrolling to an element.

number
[options.revealPadding]
optional

How much space to leave to the closest viewport edge when scrolling to an element.

string
[options.revealMax]
optional

How many pixel lines of high element to reveal when scrolling to an element.

string
[options.saveScroll=true]
optional

Whether to save scroll positions before updating the fragment.

Saved scroll positions can later be restored with { scroll: 'restore' }.

boolean

Focus

[options.focus]
optional

What to focus after the new fragment was rendered.

See Controlling focus for a list of allowed values.

booleanstringElementFunction
[options.failFocus]
optional

What to focus after the new fragment was rendered from a failed response.

See Rendering failed responses differently.

booleanstringElementFunction
[options.focusVisible='auto']
optional

Whether the focused element should have a visible focus ring.

By default focus will be visible if up.viewport.config.autoFocusVisible() returns true for the focused element and current input device.

booleanstring
[options.saveFocus=true]
optional

Whether to save focus-related state before updating the fragment.

Saved focus state can later be restored with { focus: 'restore' }.

boolean

Loading state

[options.disable]
optional

Disables form controls while the request is loading.

booleanstringElementArray
[options.placeholder]
optional

A placeholder to show within the targeted fragment while new content is loading.

Existing children of the targeted fragment will be hidden during the request. When the request ends for any reason, all changes will be reverted.

stringElementList<Node>
[options.preview]
optional

One or more previews that temporarily change the page while new content is loading.

The preview changes will be reverted automatically when the request ends for any reason.

stringFunction(up.Preview)Array
[options.feedback=true]
optional

Whether to set feedback classes while loading content.

boolean

Client state

[options.data]
optional

The data object object for the new fragment.

If the new fragment already has an [up-data] object, this option will override individual properties from that attribute.

[options.keep=true]
optional

Whether [up-keep] elements will be preserved in the updated fragments.

boolean
[options.context]
optional

An object that will be merged into the context of the current layer once the fragment is rendered.

Lifecycle hooks

[options.confirm]
optional

A message the user needs to confirm before any request or changes are made.

The message will be shown as a native browser prompt.

If the user does not confirm, no request is sent and no fragments are updated. In that case the render promise rejects with an up.AbortError.

string
[options.onLoaded]
optional

A callback that will be run when the server responds with new HTML, but before the HTML is rendered.

The callback argument is a preventable up:fragment:loaded event.

This callback will also run for failed responses.

Function(Event)
[options.onOffline]
optional

A callback that will be run when the fragment could not be loaded due to a disconnect or timeout.

The callback argument is a preventable up:fragment:offline event.

Function(Event)
[options.onRendered]
optional

A function to call when Unpoly has updated fragments.

This callback may be called zero, one or two times:

  • When the server rendered an empty response, no fragments are updated. { onRendered } is not called.
  • When the server rendered a matching fragment, it will be updated on the page. { onRendered } is called with the result.
  • When revalidation renders a second time, { onRendered } is called again with the final result.

Also see Running code after rendering.

Function(up.RenderResult)
[options.onFinished]
optional

A function to call when no further DOM changes will be caused by this render pass.

In particular:

The callback argument is the last up.RenderResult that updated a fragment. If revalidation re-rendered the fragment, it is the result from the second render pass. If no revalidation was performed, or if revalidation yielded an empty response, it is the result from the initial render pass.

Also see Awaiting postprocessing.

Function(up.RenderResult)
[options.onError]
optional

A callback that will be run when any error is thrown during the rendering process.

The callback is also called when the render pass fails due to network issues, or aborts.

Also see Handling errors.

Function(Error)

Return value

A promise that fulfills with an up.RenderResult once the page has been updated.

The promise rejects when one of the following conditions occur:

See Render lifecycle hooks for more information about handling errors, or running code after rendering.