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

# up.reload([element], [options])

Replaces the given element with a fresh copy fetched from the server.

By default, reloading is **not** considered a [user navigation](https://unpoly.com/learn/navigation-defaults.md) and will not scroll, focus or update the browser location. You may change this with `{ navigate: true }`.

<nav aria-label="Guides">

- [Learn: Live fragments](https://unpoly.com/learn/live-fragments.md)

</nav>

<nav aria-label="Contents">

#### Contents

- [Example](#example)
- [Controlling the URL that is reloaded](#controlling-the-url-that-is-reloaded)
- [Skipping updates when nothing changed](#skipping-updates-when-nothing-changed)
- [Restoring content from cache](#restoring-content-from-cache)
- [Parameters](#parameters)
- [Return value](#return-value)

</nav>

## Example {#example}

```js
let { fragment } = await up.reload('.inbox')
console.log("New .inbox element: ", fragment)
```

## Controlling the URL that is reloaded {#controlling-the-url-that-is-reloaded}

Unpoly remembers [the URL from which a fragment was loaded](https://unpoly.com/api/up-source.md), so you don't usually need to pass a URL when reloading.

To reload from another URL, pass a `{ url }` option or set an [`[up-source]`](https://unpoly.com/api/up-source.md) attribute on the element being reloaded or its ancestors.

## Skipping updates when nothing changed {#skipping-updates-when-nothing-changed}

The server can answer `304 Not Modified` when the fragment hasn't changed. See [conditional requests](https://unpoly.com/learn/conditional-requests.md).

## Restoring content from cache {#restoring-content-from-cache}

To instantly restore a fragment to the last [cached](https://unpoly.com/learn/caching.md) version, pass a `{ cache: true }` option:

```js
up.reload('.inbox', { cache: true })
```

If the fragment source isn't cached, a network request is made.

To restore a fragment from cache, but [revalidate](https://unpoly.com/learn/caching.md#revalidation) cached content that has [expired](https://unpoly.com/learn/caching.md#expiration), also pass a `{ revalidate: 'auto' }` option:

```js
up.reload('.inbox', { cache: true, revalidate: 'auto' })
```

---

## Parameters {#parameters}

### Targeting {#parameters-targeting}

#### [element] {#element}

(optional)

The element or selector that should be reloaded.

If omitted, an element matching a selector in [`up.fragment.config.mainTargets`](https://unpoly.com/api/up.fragment.config.md#config.mainTargets) will be reloaded.

When an [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element) object is passed, a target selector will be [derived](https://unpoly.com/learn/target-derivation.md).

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

### Render options {#parameters-render-options}

#### [options] {#options}

(optional)

Additional [render options](https://unpoly.com/api/up.render.md#parameters) to use when reloading the fragment.

Common options are documented below, but most [options for `up.render()`](https://unpoly.com/api/up.render.md#parameters) may be used.

Defaults can be configured in [`up.fragment.config.reloadOptions`](https://unpoly.com/api/up.fragment.config.md#config.reloadOptions) and [`up.fragment.config.renderOptions`](https://unpoly.com/api/up.fragment.config.md#config.renderOptions).

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

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

(optional)

Whether the reloading constitutes a [user navigation](https://unpoly.com/learn/navigation-defaults.md).

Type: boolean

### Request {#parameters-request}

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

(optional)

The URL from which to reload the fragment.

Defaults to the [URL from which the fragment was originally loaded](https://unpoly.com/api/up.fragment.source.md).

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=false] {#options.cache}

(optional)

Whether to restore the fragment from the [cache](https://unpoly.com/learn/caching.md).

By default the cache is ignored and a new HTTP request is sent. Pass `{ cache: true }` to restore the fragment from the cache.

Type: boolean

#### [options.revalidate=false] {#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

### Scrolling {#parameters-scrolling}

#### [options.scroll='keep'] {#options.scroll}

(optional)

Whether to scroll after the fragment was reloaded.

By default Unpoly will [keep scroll positions](https://unpoly.com/learn/scrolling.md#keep) of all viewports around the updated fragment.

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

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

### Focus {#parameters-focus}

#### [options.focus='keep'] {#options.focus}

(optional)

What to focus after the fragment was reloaded.

By default Unpoly will [keep the current focus](https://unpoly.com/learn/focus.md#keep) within the updated fragment.

See [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

### 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.keepData] {#options.keepData}

(optional)

Whether to [preserve](https://unpoly.com/learn/data.md#preserving) the fragment's [data object](https://unpoly.com/learn/data.md) throughout the update.

Properties from the new fragment's [`[up-data]`](https://unpoly.com/api/up-data.md) are overridden with the old fragment's [`[up-data]`](https://unpoly.com/api/up-data.md).

Type: boolean

#### [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)