up.fragment
up.fragment.config
JavaScript property
Configures defaults for fragment updates.
Value
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.
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.
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.
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.
An object of default options to apply when navigating.
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.
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.
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.
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
#hashin 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.
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.
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'
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 Modifiedor204 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.