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

# up.deferred.load(placeholder, [options])

Loads a [`[up-defer="manual"]`](https://unpoly.com/api/up-defer.md) placeholder.

<nav aria-label="Guides">

- [Learn: Lazy loading content](https://unpoly.com/learn/lazy-loading.md#scripted)

</nav>

---

## Parameters {#parameters}

### General {#parameters-general}

#### placeholder {#placeholder}

(required)

The [`[up-defer]`](https://unpoly.com/api/up-defer.md) placeholder to load.

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

#### [options] {#options}

(optional)

[Render options](https://unpoly.com/api/up.render.md#parameters) that should be used for loading the placeholder.

Unpoly will parse render options from the given placeholder's attributes. You may pass this additional `options` object to [supplement or override](https://unpoly.com/learn/attributes-and-options.md#options) options parsed from the placeholder attributes. See [`[up-follow]`](https://unpoly.com/api/up-follow.md) for a list of supported attributes.

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

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

### Targeting {#parameters-targeting}

#### [options.target=':origin'] {#options.target}

(optional)

A selector for the fragment to render the content in.

By default the [`[up-defer]`](https://unpoly.com/api/up-defer.md) element itself will be replaced with the loaded content. For this the element must have a [derivable target selector](https://unpoly.com/learn/target-derivation.md).

You may target one or [multiple](https://unpoly.com/learn/targeting-fragments.md#multiple) fragments. To target the placeholder itself, you can use the [`:origin`](https://unpoly.com/api/origin.md) target instead of spelling out a selector.

Type: string

### Request {#parameters-request}

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

(optional)

The URL from which to load the deferred content.

Defaults to the placeholder's [`[up-href]`](https://unpoly.com/api/up-defer.md#up-href) or `[href]` attribute.

Type: string

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

(optional)

Whether to load the deferred content [in the background](https://unpoly.com/learn/background-requests.md).

Background requests will not show the [global progress bar](https://unpoly.com/learn/progress-bar.md).

Type: 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

---

## Return value {#return-value}

A promise that fulfills with an [`up.RenderResult`](https://unpoly.com/api/up.RenderResult.md) once the deferred content has been loaded and rendered.

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