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

# up.render([target], [options])

Replaces elements on the current page with matching elements from a server response or HTML string.

<nav aria-label="Contents">

#### Contents

- [Choosing which fragment to update](#choosing-which-fragment-to-update)
- [Passing the new fragment](#passing-the-new-fragment)
- [Enabling side effects](#enabling-side-effects)
- [Hooking into the render process](#hooking-into-the-render-process)
- [Concurrency](#concurrency)
- [Parameters](#parameters)
- [Return value](#return-value)

</nav>

## Choosing which fragment to update {#choosing-which-fragment-to-update}

The current and new elements must both match the same [target selector](https://unpoly.com/learn/targeting-fragments.md). The selector is either given as `{ target }` option, or a [main target](https://unpoly.com/api/up-main.md) is used as default.

Let's say your current HTML looks like this:

```html
<div class="one">old one</div>
<div class="two">old two</div>
```

We now replace the second `<div>` by [targeting](https://unpoly.com/learn/targeting-fragments.md) its CSS class:

```js
up.render({ target: '.two', url: '/new' })
```

The server renders a response for `/new`:

```html
<div class="one">new one</div>
<div class="two">new two</div>
```

Unpoly looks for the selector `.two` in the response and places it in the current page. The current page now looks like this:

```html
<div class="one">old one</div>
<div class="two">new two</div>
```

Note how only `.two` has changed. The update for `.one` was discarded, since it didn't match the selector.

See [targeting fragments](https://unpoly.com/learn/targeting-fragments.md) for many examples for how you can target content.

## Passing the new fragment {#passing-the-new-fragment}

The new fragment content can be passed as one of the following options:

| Effect | HTML attribute | JavaScript option |
| --- | --- | --- |
| Fetch a URL and update targeted fragments | `[href]` or `[action]` | `{ url }` |
| Update a fragment's inner HTML from a string, `<template>`, or [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element) | `[up-content]` | `{ content }` |
| Update a fragment's outer HTML from a string, `<template>`, or [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element) | `[up-fragment]` | `{ fragment }` |
| Update targeted fragments from a larger HTML string | `[up-document]` | `{ document }` |
| Update targeted fragments from an existing [`up.Response`](https://unpoly.com/api/up.Response.md) object | – | `{ response }` |

See [providing HTML to render](https://unpoly.com/learn/providing-html.md) for more details and examples.

## Enabling side effects {#enabling-side-effects}

This function has many options to enable scrolling, focus, request cancellation and other side effects. These options are all disabled by default and must be opted into one-by-one.

To enable defaults that a user would expect for navigation (like clicking a link), pass [`{ navigate: true }`](#options.navigate) or use [`up.navigate()`](https://unpoly.com/api/up.navigate.md) instead.

## Hooking into the render process {#hooking-into-the-render-process}

Your code may hook into specific stages of the rendering process. This allows you to modify the rendered result or handle error cases.

See [render hooks](https://unpoly.com/learn/render-lifecycle.md) for details.

## Concurrency {#concurrency}

Unfinished requests [targeting](https://unpoly.com/learn/targeting-fragments.md) the updated fragment or its descendants are [aborted](https://unpoly.com/learn/aborting-requests.md). You may control this behavior using the [`{ abort }`](#options.abort) option.

---

## Parameters {#parameters}

### Targeting {#parameters-targeting}

#### [target] {#target}

(optional)

The [target selector](https://unpoly.com/learn/targeting-fragments.md) to update.

Instead of passing the target as the first argument, you may also pass it as a `{ target }` option. See [`{ target }`](#options.target) for details.

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [jQuery](https://learn.jquery.com/using-jquery-core/jquery-object/) | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string>

#### [options.target] {#options.target}

(optional)

The [target selector](https://unpoly.com/learn/targeting-fragments.md) to update after a successful response.

If omitted, a [main target](https://unpoly.com/api/up-main.md) will be rendered when [`{ fallback: true }`](#options.fallback) is set. [Navigation](https://unpoly.com/learn/navigation-defaults.md) sets `{ fallback: true }`, so following a link or submitting a form without a target renders a main target. A plain `up.render()` needs a `{ target }` or `{ fallback }`.

You may also pass a DOM element or jQuery element here, in which case a selector will be [derived](https://unpoly.com/learn/target-derivation.md). The given element will also be used as [`{ origin }`](#options.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.

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [jQuery](https://learn.jquery.com/using-jquery-core/jquery-object/) | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string>

#### [options.failTarget] {#options.failTarget}

(optional)

The [target selector](https://unpoly.com/learn/targeting-fragments.md) to update when the server responds with an error code.

See [Rendering error responses differently](https://unpoly.com/learn/error-responses.md#fail-options).

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [jQuery](https://learn.jquery.com/using-jquery-core/jquery-object/) | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<string>

#### [options.fallback] {#options.fallback}

(optional)

Specifies behavior if the [target selector](https://unpoly.com/learn/targeting-fragments.md) 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](https://unpoly.com/api/up-main.md) instead.

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

Also see [Dealing with missing targets](https://unpoly.com/learn/targeting-fragments.md#missing-targets).

Type: string | boolean

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

(optional)

Controls which fragment to update when the [`{ target }`](#options.target) selector yields multiple results.

When set to `'region'`, Unpoly will prefer to update 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 update the first matching fragment.

Defaults to [`up.fragment.config.match`](https://unpoly.com/api/up.fragment.config.md#config.match), which defaults to `'region'`.

Type: string

#### [options.origin] {#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](https://unpoly.com/learn/targeting-fragments.md#ambiguous-selectors).

The origin's selector will be substituted for [`:origin`](https://unpoly.com/api/origin.md) in a [target selector](https://unpoly.com/learn/targeting-fragments.md).

Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [jQuery](https://learn.jquery.com/using-jquery-core/jquery-object/)

#### [options.hungry=true] (Experimental) {#options.hungry}

(optional)

Whether [`[up-hungry]`](https://unpoly.com/api/up-hungry.md) elements outside the updated fragment will also be updated.

Type: boolean

### Navigation {#parameters-navigation}

#### [options.navigate=false] {#options.navigate}

(optional)

Whether this fragment update is considered [navigation](https://unpoly.com/learn/navigation-defaults.md).

Setting this to `true` will enable many side effects, like [updating history](https://unpoly.com/learn/updating-history.md) or [scrolling](https://unpoly.com/learn/scrolling.md).

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

Type: boolean

### Request {#parameters-request}

#### [options.url] {#options.url}

(optional)

The URL to request from the server.

See [loading content from a URL](https://unpoly.com/learn/providing-html.md#url).

Type: string

#### [options.method='get'] {#options.method}

(optional)

The HTTP method to use for the request.

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

Type: string

#### [options.params] {#options.params}

(optional)

Additional [parameters](https://unpoly.com/api/up.Params.md) that should be sent as the request's [query string](https://en.wikipedia.org/wiki/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.

Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects) | [up.Params](https://unpoly.com/api/up.Params.md) | [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) | string | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

#### [options.headers={}] {#options.headers}

(optional)

An object with additional request headers.

Unpoly will by default send a number of custom request headers. For example, the [`X-Up-Target`](https://unpoly.com/api/X-Up-Target.md) header includes the [targeted](https://unpoly.com/learn/targeting-fragments.md) CSS selector. See [`up.protocol`](https://unpoly.com/api/up.protocol.md) for details.

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

#### [options.abort='target'] {#options.abort}

(optional)

Whether to abort existing requests before rendering.

See [aborting requests](https://unpoly.com/learn/aborting-requests.md) for details and a list of options.

Type: boolean | string | Function(request): boolean

#### [options.abortable=true] {#options.abortable}

(optional)

Whether the request may be aborted by other requests [targeting](https://unpoly.com/learn/targeting-fragments.md) the same fragments or layer.

See [Aborting rules in layers](https://unpoly.com/learn/aborting-requests.md#layers).

Type: boolean

#### [options.background=false] {#options.background}

(optional)

Whether this request will load in the background.

Background requests are deprioritized and won't show the [progress bar](https://unpoly.com/learn/progress-bar.md). See [Background requests](https://unpoly.com/learn/background-requests.md).

Type: boolean

#### [options.lateDelay] {#options.lateDelay}

(optional)

The number of milliseconds after which this request can cause an [`up:network:late`](https://unpoly.com/api/up:network:late.md) event and show the [progress bar](https://unpoly.com/learn/progress-bar.md).

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

Defaults to [`up.network.config.lateDelay`](https://unpoly.com/api/up.network.config.md#config.lateDelay).

Type: number | boolean

#### [options.timeout] {#options.timeout}

(optional)

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

Defaults to [`up.network.config.timeout`](https://unpoly.com/api/up.network.config.md#config.timeout).

Type: number

#### [options.fail] {#options.fail}

(optional)

Whether to render [error responses](https://unpoly.com/learn/error-responses.md) differently.

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

By [default](https://unpoly.com/api/up.network.config.md#config.fail) any HTTP status code other than 2xx or 304 is considered an error response. Pass `{ fail: false }` to handle _any_ response as successful, even with a 4xx or 5xx status code.

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

### Caching {#parameters-caching}

#### [options.cache] {#options.cache}

(optional)

Whether to read from and write to the [cache](https://unpoly.com/learn/caching.md).

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](#options.revalidate). 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`](https://unpoly.com/api/up.network.config.md#config.autoCache) returns `true` for the request.

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

Type: boolean

#### [options.revalidate] {#options.revalidate}

(optional)

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

With `{ revalidate: 'auto' }` Unpoly will revalidate [expired](https://unpoly.com/learn/caching.md#expiration) responses. This behavior can be configured with [`up.fragment.config.autoRevalidate(response)`](https://unpoly.com/api/up.fragment.config.md#config.autoRevalidate).

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

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

Type: boolean | string

#### [options.revalidatePreview] (Experimental) {#options.revalidatePreview}

(optional)

A [preview](https://unpoly.com/learn/previews.md) that runs while [revalidating cached content](https://unpoly.com/learn/caching.md#revalidation).

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

#### [options.expireCache] {#options.expireCache}

(optional)

Whether existing [cache](https://unpoly.com/learn/caching.md) entries will be [expired](https://unpoly.com/learn/caching.md#expiration) when this request is sent.

Expired content remains in the cache, but will be [revalidated](https://unpoly.com/learn/caching.md#revalidation) 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`](https://unpoly.com/api/up.network.config.md#config.expireCache). Pass `false` to not expire any cache entries.

To only expire some requests, pass a [URL pattern](https://unpoly.com/api/url-patterns.md) that matches requests to uncache. You may also pass a function that accepts an existing [`up.Request`](https://unpoly.com/api/up.Request.md) and returns a boolean value.

Type: boolean | string

#### [options.evictCache] {#options.evictCache}

(optional)

Whether existing [cache](https://unpoly.com/learn/caching.md) entries will be [evicted](https://unpoly.com/learn/caching.md#eviction) when this request is sent.

By default, Unpoly will never evict entries while the cache has [space](https://unpoly.com/api/up.network.config.md#config.cacheSize), preferring [expiration](https://unpoly.com/learn/caching.md#expiration) instead. This can be configured with [`up.network.config.evictCache`](https://unpoly.com/api/up.network.config.md#config.evictCache).

To only evict some requests, pass a [URL pattern](https://unpoly.com/api/url-patterns.md) that matches requests to uncache. You may also pass a function that accepts an existing [`up.Request`](https://unpoly.com/api/up.Request.md) and returns a boolean value.

Type: boolean | string

### Local content {#parameters-local-content}

#### [options.content] {#options.content}

(optional)

The new [inner HTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML) for the targeted fragment.

See [Updating an element's inner HTML from a string](https://unpoly.com/learn/providing-html.md#content).

Instead of passing an HTML string you can also [refer to a template](https://unpoly.com/learn/templates.md).

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [List](https://unpoly.com/api/List.md)<[Node](https://developer.mozilla.org/en-US/docs/Web/API/Node)>

#### [options.fragment] {#options.fragment}

(optional)

A string of HTML comprising only the new fragment's [outer HTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML).

When passing `{ fragment }` you can omit the `{ target }` option. The target will be [derived](https://unpoly.com/learn/target-derivation.md) from the root element in the given HTML.

See [Rendering a string that only contains the fragment](https://unpoly.com/learn/providing-html.md#fragment).

Instead of passing an HTML string you can also [refer to a template](https://unpoly.com/learn/templates.md).

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)

#### [options.document] {#options.document}

(optional)

A string of HTML containing the targeted fragment.

See [Extracting an element's outer HTML from a larger HTML string](https://unpoly.com/learn/providing-html.md#document).

Instead of passing an HTML string you can also [refer to a template](https://unpoly.com/learn/templates.md).

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | Document

#### [options.response] {#options.response}

(optional)

An [`up.Response`](https://unpoly.com/api/up.Response.md) object that contains the targeted fragments in its [text](https://unpoly.com/api/up.Response.prototype.text.md).

See [Rendering an up.Response object](https://unpoly.com/learn/providing-html.md#response).

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

### Layer {#parameters-layer}

#### [options.layer='origin, current'] {#options.layer}

(optional)

The [layer](https://unpoly.com/api/up.layer.md) in which to match and render the fragment.

See [layer option](https://unpoly.com/learn/targeting-other-layers.md) for a list of allowed values.

To [open the fragment in a new overlay](https://unpoly.com/learn/opening-overlays.md), pass `{ layer: 'new' }`. In this case options for [`up.layer.open()`](https://unpoly.com/api/up.layer.open.md) may also be used.

Type: string | [up.Layer](https://unpoly.com/api/up.Layer.md) | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)

#### [options.failLayer='origin, current'] {#options.failLayer}

(optional)

The [layer](https://unpoly.com/api/up.layer.md) in which to render if the server responds with an error code.

See [Rendering error responses differently](https://unpoly.com/learn/error-responses.md#fail-options).

Type: string | [up.Layer](https://unpoly.com/api/up.Layer.md) | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)

#### [options.peel] {#options.peel}

(optional)

Whether to close overlays obstructing the target layer, when [updating a background layer from an overlay](https://unpoly.com/learn/closing-overlays.md#peeling).

To [dismiss](https://unpoly.com/learn/closing-overlays.md#intents) obstructing overlays, pass `{ peel: true }` or `{ peel: 'dismiss' }`.
To [accept](https://unpoly.com/learn/closing-overlays.md#intents) obstructing overlays, pass `{ peel: 'accept' }`.
To not peel, pass `{ peel: false }`.

Type: boolean | string

### History {#parameters-history}

#### [options.history] {#options.history}

(optional)

Whether the browser URL, window title and meta tags will be [updated](https://unpoly.com/learn/updating-history.md).

If set to `true`, history will be updated, except for aspects that [`up.history.config.enabled`](https://unpoly.com/api/up.history.config.md#config.enabled) [turns off](https://unpoly.com/learn/updating-history.md#disabling).

If set to `'auto'` history will be updated if the `{ target }` matches a selector in [`up.fragment.config.autoHistoryTargets`](https://unpoly.com/api/up.fragment.config.md#config.autoHistoryTargets). By default this contains all [main targets](https://unpoly.com/api/main.md).

If set to `false`, the history will remain unchanged.

See [Updating history](https://unpoly.com/learn/updating-history.md).

Type: boolean | string

#### [options.failHistory] {#options.failHistory}

(optional)

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

See [Rendering error responses differently](https://unpoly.com/learn/error-responses.md#fail-options).

Type: boolean | string

#### [options.title] {#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](#options.history).

Type: boolean | string

#### [options.location] {#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](#options.history).

Type: boolean | string

#### [options.metaTags] {#options.metaTags}

(optional)

Whether to update [meta tags](https://unpoly.com/api/up-meta.md) 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](#options.history).

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

#### [options.lang] {#options.lang}

(optional)

An explicit language code to set as the [`html[lang]`](https://www.tpgi.com/using-the-html-lang-attribute/) attribute.

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

This option is only used when [updating history](#options.history).

Type: boolean | string

### Animation {#parameters-animation}

#### [options.transition] {#options.transition}

(optional)

The name of a [transition](https://unpoly.com/api/up.motion.md) to morph between the old and new fragment.

If you are [prepending or appending content](https://unpoly.com/learn/targeting-fragments.md#appending-or-prepending), use the `{ animation }` option instead.

Type: string

#### [options.animation] {#options.animation}

(optional)

The name of an [animation](https://unpoly.com/learn/animations.md) to play on the new content when [prepending or appending content](https://unpoly.com/learn/targeting-fragments.md#appending-or-prepending).

If you are [swapping a fragment](https://unpoly.com/learn/targeting-fragments.md#swapping) (the default), use the `{ transition }` option instead.

Type: string

#### [options.duration] {#options.duration}

(optional)

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

Type: number

#### [options.easing] {#options.easing}

(optional)

The timing function that accelerates the transition or animation.

See [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) for a list of available timing functions.

Type: string

### Scrolling {#parameters-scrolling}

#### [options.scroll] {#options.scroll}

(optional)

How to scroll after the new fragment was rendered.

See [scrolling](https://unpoly.com/learn/scrolling.md) for a list of allowed values.

When [updating multiple fragments](https://unpoly.com/learn/targeting-fragments.md#multiple), this option will only be applied to the _first_ fragment. To scroll other fragments, use [`{ scrollMap }`](#options.scrollMap).

Type: boolean | string | number | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | Function

#### [options.failScroll] {#options.failScroll}

(optional)

How to scroll after the new fragment was rendered from an error response.

See [Rendering error responses differently](https://unpoly.com/learn/error-responses.md#fail-options).

Type: boolean | string | number | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | Function

#### [options.scrollMap] {#options.scrollMap}

(optional)

An object mapping fragment selectors to a [scrolling option](https://unpoly.com/learn/scrolling.md).

When a scroll map is given, the [`{ scroll }`](#options.scroll) option is ignored.

See [Scrolling multiple viewports](https://unpoly.com/learn/scrolling.md#multiple-viewports) for examples.

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

#### [options.scrollBehavior='instant'] {#options.scrollBehavior}

(optional)

Whether to [animate the scroll motion](https://unpoly.com/learn/scroll-tuning.md#animating-the-scroll-motion).

Type: string

#### [options.revealSnap] {#options.revealSnap}

(optional)

When to [snap to the top](https://unpoly.com/learn/scroll-tuning.md#snapping-to-the-screen-edge) when scrolling to an element near the top edge of the viewport's scroll buffer.

Type: number

#### [options.revealTop] {#options.revealTop}

(optional)

When to [move a revealed element to the top](https://unpoly.com/learn/scroll-tuning.md#moving-revealed-elements-to-the-top) when scrolling to an element.

Type: boolean

#### [options.revealPadding] {#options.revealPadding}

(optional)

How much [space to leave to the closest viewport edge](https://unpoly.com/learn/scroll-tuning.md#revealing-with-padding) when scrolling to an element.

Type: number

#### [options.revealMax] {#options.revealMax}

(optional)

How many pixel lines of a [tall element to reveal](https://unpoly.com/learn/scroll-tuning.md#revealing-large-elements) when scrolling to an element.

Type: number | Function

#### [options.saveScroll=true] {#options.saveScroll}

(optional)

Whether to [save scroll positions](https://unpoly.com/api/up.viewport.saveScroll.md) before updating the fragment.

Saved scroll positions can later be restored with [`{ scroll: 'restore' }`](https://unpoly.com/learn/scrolling.md#restore).

Type: boolean

### Focus {#parameters-focus}

#### [options.focus] {#options.focus}

(optional)

What to focus after the new fragment was rendered.

See [Controlling focus](https://unpoly.com/learn/focus.md) for a list of allowed values.

Type: boolean | string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | Function

#### [options.failFocus] {#options.failFocus}

(optional)

What to focus after the new fragment was rendered from an error response.

See [Rendering error responses differently](https://unpoly.com/learn/error-responses.md#fail-options).

Type: boolean | string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | Function

#### [options.focusVisible='auto'] {#options.focusVisible}

(optional)

Whether the focused element should have a [visible focus ring](https://unpoly.com/learn/focus-visibility.md).

By default focus will be visible if [`up.viewport.config.autoFocusVisible()`](https://unpoly.com/api/up.viewport.config.md#config.autoFocusVisible) returns `true` for the focused element and the [input device](https://unpoly.com/api/up.event.inputDevice.md) of the interaction that started the render pass.

Type: boolean | string

#### [options.saveFocus=true] {#options.saveFocus}

(optional)

Whether to [save focus-related state](https://unpoly.com/api/up.viewport.saveFocus.md) before updating the fragment.

Saved focus state can later be restored with [`{ focus: 'restore' }`](https://unpoly.com/learn/focus.md#restore).

Type: boolean

### Loading state {#parameters-loading-state}

#### [options.disable] {#options.disable}

(optional)

[Disables form controls](https://unpoly.com/learn/disabling-forms.md) while the request is loading.

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

#### [options.placeholder] (Experimental) {#options.placeholder}

(optional)

A [placeholder](https://unpoly.com/learn/placeholders.md) to show within the targeted fragment while new content is loading.

Existing children of the targeted fragment [will be hidden](https://unpoly.com/learn/placeholders.md#basic-example) during the request. When the request ends for any reason, all changes will be reverted.

Type: string | [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | [List](https://unpoly.com/api/List.md)<[Node](https://developer.mozilla.org/en-US/docs/Web/API/Node)>

#### [options.preview] {#options.preview}

(optional)

One or more [previews](https://unpoly.com/learn/previews.md) that temporarily change the page while new content is loading.

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

Type: string | Function([up.Preview](https://unpoly.com/api/up.Preview.md)) | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

#### [options.feedback=true] {#options.feedback}

(optional)

Whether to set [feedback classes](https://unpoly.com/learn/feedback-classes.md) while loading content.

Type: boolean

### Client state {#parameters-client-state}

#### [options.data] {#options.data}

(optional)

The [data](https://unpoly.com/learn/data.md) object for the new fragment.

If the new fragment already has an [`[up-data]`](https://unpoly.com/api/up-data.md) object, properties from `{ data }` take precedence.

When updating [multiple fragments](https://unpoly.com/learn/targeting-fragments.md#multiple), `{ data }` is only applied to the primary fragment. To apply data to multiple fragments, use [`{ dataMap }`](#options.dataMap).

See [Overriding data for a render pass](https://unpoly.com/learn/data.md#override).

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

#### [options.dataMap] (Experimental) {#options.dataMap}

(optional)

An object mapping selectors to [data objects](https://unpoly.com/learn/data.md).

When a selector matches any element within an updated fragment, the matching element is compiled with the mapped data.

See [Mapping selectors to data](https://unpoly.com/learn/data.md#map).

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

#### [options.keep=true] (Experimental) {#options.keep}

(optional)

Whether [`[up-keep]`](https://unpoly.com/api/up-keep.md) elements will be kept in the updated fragments.

Type: boolean

#### [options.context] (Experimental) {#options.context}

(optional)

An object that will be merged into the [context](https://unpoly.com/learn/layer-context.md) of the current layer once the fragment is rendered.

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

### Lifecycle hooks {#parameters-lifecycle-hooks}

#### [options.confirm] {#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 confirmation dialog](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm).

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.Aborted` error.

See [Confirmation dialogs](https://unpoly.com/learn/confirmation-dialogs.md), also for showing a styled dialog instead of the browser's.

Type: string

#### [options.onLoaded] {#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`](https://unpoly.com/api/up:fragment:loaded.md) event.

This callback will also run for [error responses](https://unpoly.com/learn/error-responses.md).

Type: Function([Event](https://developer.mozilla.org/en-US/docs/Web/API/Event))

#### [options.onOffline] {#options.onOffline}

(optional)

A callback that will be run when the fragment could not be loaded due to a [disconnect or timeout](https://unpoly.com/learn/network-issues.md).

The callback argument is an [`up:fragment:offline`](https://unpoly.com/api/up:fragment:offline.md) event. To try again, call `event.retry()`.

Type: Function([Event](https://developer.mozilla.org/en-US/docs/Web/API/Event))

#### [options.onRendered] {#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](https://unpoly.com/learn/conditional-requests.md#rendering-nothing), 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](https://unpoly.com/api/up.RenderResult.md).
- When [revalidation](https://unpoly.com/learn/caching.md#revalidation) renders a second time, `{ onRendered }` is called again with the final result.

Also see [Running code after rendering](https://unpoly.com/learn/render-lifecycle.md#running-code-after-rendering).

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

#### [options.onFinished] {#options.onFinished}

(optional)

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

The following state is considered "finished":

- [Animations](https://unpoly.com/api/up.motion.md) have concluded and [transitioned](https://unpoly.com/api/up-transition.md) elements have been removed from the DOM tree.
- [Async compilers](https://unpoly.com/api/up.compiler.md#async) have settled.
- [Cached content](https://unpoly.com/learn/caching.md) has been [revalidated with the server](https://unpoly.com/learn/caching.md#revalidation).
  If the server has responded with fresher content, that content has also been rendered.

The callback argument is the last [`up.RenderResult`](https://unpoly.com/api/up.RenderResult.md) that updated a fragment. If [revalidation](https://unpoly.com/learn/caching.md#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](https://unpoly.com/learn/caching.md#when-nothing-changed), it is the result from the initial render pass.

To run a callback after an [error response](https://unpoly.com/learn/error-responses.md) has finished rendering, pass an `{ onFailFinished }` option instead.

When a [revalidation](https://unpoly.com/learn/caching.md#revalidation) receives an error response, `{ onFinished }` is not called. Instead `{ onFailRendered }` and `{ onFailFinished }` are called for the revalidation's error response.

Also see [Awaiting post-processing](https://unpoly.com/learn/render-lifecycle.md#postprocessing).

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

#### [options.onError] {#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](https://unpoly.com/learn/network-issues.md), or [aborts](https://unpoly.com/learn/aborting-requests.md).

Also see [Handling errors](https://unpoly.com/learn/render-lifecycle.md#handling-errors).

Type: Function([Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error))

---

## Return value {#return-value}

A promise that fulfills with an [`up.RenderResult`](https://unpoly.com/api/up.RenderResult.md) once the page has been updated.

The promise rejects when one of the following conditions occur:

- the render pass was [aborted](https://unpoly.com/learn/aborting-requests.md)
- the server sends an [error status](https://unpoly.com/learn/error-responses.md)
- there is a [network issue](https://unpoly.com/learn/network-issues.md)
- [targets](https://unpoly.com/learn/targeting-fragments.md) could not be matched

See [Render lifecycle hooks](https://unpoly.com/learn/render-lifecycle.md) for more information about handling errors, or running code after rendering.

Type: [up.RenderJob](https://unpoly.com/api/up.RenderJob.md)