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

# up.submit(form, [options])

Submits a form via JavaScript and updates a fragment with the server response.

The server must render an element matching the [target selector](https://unpoly.com/learn/targeting-fragments.md) from the `{ target }` option or the form's `[up-target]` attribute. A matching element in the current page is then swapped with the new element from the server response. The response may include other HTML (even an entire HTML document), but only the matching element will be updated.

Submitting a form is considered [navigation](https://unpoly.com/learn/navigation-defaults.md).

Emits the event [`up:form:submit`](https://unpoly.com/api/up:form:submit.md).

<nav aria-label="Guides">

- [Learn: Submitting forms](https://unpoly.com/learn/submitting-forms.md)

</nav>

<nav aria-label="Contents">

#### Contents

- [Example](#example)
- [Parameters](#parameters)
- [Return value](#return-value)

</nav>

## Example {#example}

```js
up.submit('form.new-user', { target: '.main' })
```

---

## Parameters {#parameters}

### General {#parameters-general}

#### form {#form}

(required)

The form to submit.

If the argument points to an element that is not a form, Unpoly will search its ancestors for the [closest](https://unpoly.com/api/up.fragment.closest.md) form.

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

#### [options] {#options}

(optional)

Additional [render options](https://unpoly.com/api/up.render.md#parameters) that should be used for submitting the form.

Unpoly will parse render options from the form'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 attributes. See [`[up-submit]`](https://unpoly.com/api/up-submit.md) for a list of supported attributes.

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

### Targeting {#parameters-targeting}

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

By default, error responses will update the `<form>` element itself.

See [Handling error responses](https://unpoly.com/learn/error-responses.md).

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 form submission.

This defaults to the first applicable:

- An element within the form that was focused when the form was submitted (e.g. when the user presses `Enter` inside a text field)
- The [button clicked to submit the form](https://unpoly.com/api/up:form:submit.md#event.submitButton).
- The first submit button
- The `<form>` element

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=true] {#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)

Where to send the form data when the form is submitted.

Defaults to the form's `[action]` attribute.

Type: string

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

(optional)

The HTTP method to use for the request.

Defaults to the form's `[method]` attribute.

The value is case-insensitive.

You can also use methods that would not be allowed on a `<form>` element, such as `'patch'` or `'delete'`. These will be [wrapped in a POST request](https://unpoly.com/api/up.network.config.md#config.wrapMethod).

Type: string

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

(optional)

Additional [Form 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.

The given value will be added to params [parsed](https://unpoly.com/api/up.Params.fromForm.md) from the form's input fields. If a param with the same name already existed in the form, it will be deleted and overridden with the given value.

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

#### [options.submitButton] {#options.submitButton}

(optional)

The submit button used to submit the form. The button must belong to the form, or an error is thrown.

If the submit button has a `[name]` and `[value]` attribute, it will be included in the request params.

By default, the form's first submit button will be assumed. Pass `{ submitButton: false }` to not assume any submit button.

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

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

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

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

The values of disabled fields will still be included in the submitted form params.

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)