---
name: "up.fragment.config"
area: "API"
kind: "Configuration object"
parent: "up.fragment module"
url: "https://unpoly.com/api/up.fragment.config"
---
<nav aria-label="Unpoly docs">[All docs](https://unpoly.com/index.md) · [up.fragment module](https://unpoly.com/api/up.fragment.md)</nav>

# up.fragment.config

Configures defaults for fragment updates.

---

## Value {#value}

### Targeting {#value-targeting}

#### [config.mainTargets=['[up-main]', 'main', ':layer']] {#config.mainTargets}

(optional)

An array of CSS selectors matching default [render targets](https://unpoly.com/learn/targeting-fragments.md).

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

When [navigating](https://unpoly.com/learn/navigation-defaults.md) to a main target, Unpoly will automatically [reset scroll positions](https://unpoly.com/learn/scrolling.md#auto) and [update the browser history](https://unpoly.com/learn/updating-history.md).

This property is aliased as [`up.layer.config.any.mainTargets`](https://unpoly.com/api/up.layer.config.md#config.any.mainTargets).

Also see [targeting the main fragment](https://unpoly.com/learn/targeting-fragments.md#targeting-the-main-element).

Type: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string>

#### [config.targetDerivers] {#config.targetDerivers}

(optional)

An array of [target derivation patterns](https://unpoly.com/learn/target-derivation.md#derivation-patterns) used to [guess a target selector](https://unpoly.com/learn/target-derivation.md) for an element.

For instance, a 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`](https://developer.mozilla.org/en-US/docs/Web/API/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.

Type: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string|Function<[Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)>: string|undefined>

#### [config.badTargetClasses] {#config.badTargetClasses}

(optional)

An array of class names that should be ignored when [deriving a target selector from a fragment](https://unpoly.com/learn/target-derivation.md).

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

Type: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string|RegExp>

#### [config.verifyDerivedTarget=true] {#config.verifyDerivedTarget}

(optional)

Whether [derived targets](https://unpoly.com/learn/target-derivation.md) must match the element to be applicable.

When verification is disabled, the first applicable [derivation pattern](https://unpoly.com/learn/target-derivation.md#derivation-patterns) will be used, even if the produced target would match another element on the page.

Also see [Derived target verification](https://unpoly.com/learn/target-derivation.md#verification).

Type: boolean

#### [config.match='region'] {#config.match}

(optional)

How to match fragments when a [target selector](https://unpoly.com/learn/targeting-fragments.md) yields multiple results.

When set to `'region'` Unpoly will prefer to match fragments in the [region](https://unpoly.com/learn/targeting-fragments.md#ambiguous-selectors) of the [origin element](https://unpoly.com/api/up.render.md#options.origin).

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

Type: string

### Render options {#value-render-options}

#### [config.navigateOptions] {#config.navigateOptions}

(optional)

An object of default render options to apply when [navigating](https://unpoly.com/learn/navigation-defaults.md).

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

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

#### [config.renderOptions] (Experimental) {#config.renderOptions}

(optional)

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

When [navigating](https://unpoly.com/learn/navigation-defaults.md), 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`.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

#### [config.reloadOptions] (Experimental) {#config.reloadOptions}

(optional)

An object of default render options to apply when [reloading fragments](https://unpoly.com/api/up.reload.md).

To set defaults for _all_ render passes (when reloading or not), use `up.fragment.config.renderOptions`.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)

#### [config.autoHistoryTargets] {#config.autoHistoryTargets}

(optional)

When an updated fragment contains an element matching one of the given [target selectors](https://unpoly.com/learn/targeting-fragments.md), history will be updated with `{ history: 'auto' }`.

By default Unpoly will auto-update history when updating a [main target](#config.mainTargets).

Type: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string>

#### [config.autoScroll] {#config.autoScroll}

(optional)

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

See [Scrolling](https://unpoly.com/learn/scrolling.md) 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](https://unpoly.com/api/up-main.md), reset scroll positions.

Type: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<boolean|string|Function([Element](https://developer.mozilla.org/en-US/docs/Web/API/Element))>

#### [config.autoFocus] {#config.autoFocus}

(optional)

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

See [Controlling focus](https://unpoly.com/learn/focus.md) 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](https://unpoly.com/api/up-main.md), focus the new fragment.
- If focus was lost with the old fragment, re-focus a [similar](https://unpoly.com/learn/target-derivation.md) element.
- If focus was lost with the old fragment, focus the new fragment.

Type: [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<boolean|string|Function([Element](https://developer.mozilla.org/en-US/docs/Web/API/Element))>

### Preprocessing {#value-preprocessing}

#### [config.normalizeKeepHTML] {#config.normalizeKeepHTML}

(optional)

A function that normalizes a HTML string before comparison with [`[up-keep="same-html"]`](https://unpoly.com/learn/keeping-elements.md#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 the default. For example, the following would only strip leading and trailing whitespace:

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

See [Keeping an element until its HTML changes](https://unpoly.com/learn/keeping-elements.md#same-html) for context.

Type: Function(string): string

### Responses {#value-responses}

#### [config.autoRevalidate] {#config.autoRevalidate}

(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.network.config.cacheExpireAge`](https://unpoly.com/api/up.network.config.md#config.cacheExpireAge):

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

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

```js
up.fragment.config.autoRevalidate = (response) => response.expired && response.url != '/dashboard'
```

Type: boolean | Function([up.Response](https://unpoly.com/api/up.Response.md)): boolean

#### [config.skipResponse] {#config.skipResponse}

(optional)

When to finish a render pass without changes, usually to [not re-insert identical content](https://unpoly.com/learn/render-lifecycle.md#skipping-responses).

By default Unpoly skips the following responses:

- Responses without text in their body. Such responses occur when the server answers a [conditional request](https://unpoly.com/learn/conditional-requests.md) with `304 Not Modified`, or responds with `204 No Content`.
- When [revalidating](https://unpoly.com/learn/caching.md#revalidation), if the expired response and fresh response have the exact same text.

The configured function accepts an object with the same properties as an [`up:fragment:loaded`](https://unpoly.com/api/up:fragment:loaded.md) event. You can provide a different function to use your own logic. For example, the following would never skip a response by default:

```js
up.fragment.config.skipResponse = ({ response, expiredResponse }) => false
```

You may also skip responses by calling `event.skip()` on an [`up:fragment:loaded`](https://unpoly.com/api/up:fragment:loaded.md) event.

Type: Function([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)): boolean

### General {#value-general}

#### [config.renderableResponse] (Experimental) {#config.renderableResponse}

(optional)

Whether the given response has a [content-type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) that is considered renderable.

By default Unpoly renders responses with an [HTML content-type](https://unpoly.com/api/up.Response.prototype.isHTML.md). Trying to render responses with a different type will throw an error, even if the response body contains HTML markup.

Restricting content types is a security precaution. It protects in a hypothetical scenario where an attacker can both upload a file _and_ can use an existing XSS vulnerability to cause Unpoly to render that file. It doesn't affect applications that reliably escape user input.

To render _any_ response regardless of content-type, configure a function that always returns `true`:

```js
up.fragment.config.renderableResponse = (response) => true
```

Type: Function([up.Response](https://unpoly.com/api/up.Response.md)): boolean