up.fragment up.fragment.config

Configuration object

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.

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.

An object of default render options to apply when navigating.

To set defaults for all render passes (when navigating or not), use up.fragment.config.renderOptions.

An object of low-level render options to apply to any render pass.

When navigating, the defaults from up.fragment.config.navigateOptions will also be applied.

Important

By design only a minimal set of options is configured. This is to spare callers from excessive unsetting of defaults when rendering a fragment without navigation. Any opinionated settings (in particular { cache, history, scroll }) should be configured in up.fragment.config.navigateOptions.

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.

An array of scroll strategies to try after updating a fragment with { scroll: 'auto' }.

See Scrolling for available strategies.

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.

An array of focus strategies when updating a fragment with { focus: 'auto' }.

See Controlling focus for available strategies.

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.

Whether to load or execute <script> tags in updated fragments.

See Running inline <script> tags for details.

A function that normalizes a HTML string before comparison with [up-keep="same-html"].

By default only light normalization is applied:

• Line indentation is ignored.
• Some fluctuating attributes are ignored, such as CSP nonces.

You can configure your own normalization instead of your own. For example, the following would only strip leading and trailing whitespace:

up.fragment.config.normalizeKeepHTML = (str) => str.trim()

See Keeping an element until its HTML changes for context.

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 finish 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.