Edit this page

up.fragment up.fragment.config
JavaScript property

Configures defaults for fragment updates.


[config.mainTargets=['[up-main]', 'main', ':layer']] Array<string> optional

An array of CSS selectors matching default render targets.

When no explicit target is given, Unpoly will update the first selector matching both the current page and the server response.

When navigating to a main target, Unpoly will automatically reset scroll positions and update the browser history.

This property is aliased as up.layer.config.any.mainTargets.

Also see targeting the main element.

[config.targetDerivers] Array<stringorFunction<Element>: stringorundefined> optional

An array of target derivation patterns used to guess a target selector for an element.

For instance, a pattern pattern 'a[href]' is applicable to all <a href="..."> elements. It produces a target like a[href="/users"].

If your deriver can't be expressed in a pattern string, you may also add a function that accepts an Element and returns a target selector, if applicable. If the function is not applicable it may return undefined. In that case the next pattern will be tried.

[config.badTargetClasses] Array<stringorRegExp> optional

An array of class names that should be ignored when deriving a target selector from a fragment.

The class names may also be passed as a regular expression.

[config.verifyDerivedTarget=true] boolean optional

Whether derived targets must match the element to be applicable.

When verification is disabled, the first applicable derivation pattern will be used, even if the produced target would match another element on the page.

Also see Derived target verification.

[config.navigateOptions] Object optional

An object of default options to apply when navigating.

[config.match='region'] string optional

How to match fragments when a target selector yields multiple results.

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

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

[config.autoHistoryTargets] Array<string> optional

When an updated fragments contain an element matching one of the given target selectors, history will be updated with { history: 'auto' }.

By default Unpoly will auto-update history when updating a main target.

[config.autoScroll] booleanorstringorFunction(Element) optional

How to scroll after updating a fragment with { scroll: 'auto' }.

See Scrolling for a list of allowed values.

The default configuration tries, in this order:

  • If the URL has a #hash, scroll to the hash.
  • If updating a main target, reset scroll positions.
[config.autoFocus] booleanorstringorFunction(Element) optional

How to focus when updating a fragment with { focus: 'auto' }.

See Controlling focus for a list of allowed values.

The default configuration tries the following strategies, in this order:

  • Focus a #hash in the URL.
  • Focus an [autofocus] element in the new fragment.
  • If updating a main target, focus the new fragment.
  • If focus was lost with the old fragment, re-focus a similar element.
  • If focus was lost with the old fragment, focus the new fragment.
[config.runScripts=true] boolean optional

Whether to execute <script> tags in updated fragments.

Scripts will load asynchronously, with no guarantee of execution order.

Note that the <body> element is a default [main target](/main. If you are including your global application scripts at the end of your <body> for performance reasons, swapping the <body> will re-execute these scripts. In that case you can configure a different main target or move your scripts to the <head> with a [defer] attribute, which is even better for performance.

[config.autoRevalidate] booleanorFunction(up.Response): boolean optional

Whether to reload a fragment after it was rendered from a cached response with { revalidate: 'auto' }.

By default Unpoly verifies cached responses that are older than up.fragment.config.expireAge:

up.fragment.config.autoRevalidate = (response) => response.expired

You can exempt server paths from being auto-revalidated like this:

up.fragment.config.autoRevalidate = (response) => response.expired && response.url != '/dashboard'
[config.skipResponse] Function(Object): boolean optional experimental

When to finishes a render pass without changes, usually to not re-insert identical content.

The configured function accepts an object with the same properties as an up:fragment:loaded event.

By default Unpoly skips the following responses:

  • Responses without text in their body. Such responses occur when a conditional request in answered with HTTP status 304 Not Modified or 204 No Content.
  • When revalidating, if the expired response and fresh response have the exact same text.

You may also skip responses by calling event.skip() on an up:fragment:loaded event.