Edit this page

up.form [up-submit]
HTML selector

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

The server must render an element matching the target selector from the [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.

Example

This will submit the form in-page and update a fragment matching .content:

<form method="post" action="/users" up-submit up-target=".content">
  ...
</form>

Handling validation errors

When the form could not be submitted due to invalid user input, Unpoly can re-render the form with validation errors.

See validating forms for details and examples.

Showing that the form is processing

See Loading state and Disabling form controls while working.

Short notation

You may omit the [up-submit] attribute if the form has one of the following attributes:

Such a form will still be submitted through Unpoly.

Handling all forms automatically

You can configure Unpoly to handle all forms on a page without requiring an [up-submit] attribute.

See Handling all links and forms.


Targeting

[up-target=':main']
optional

The target selector to update for a successful form submission.

[up-fail-target=':main']
optional

The target selector to update when the server responds with an error code.

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

See Handling failed responses.

[up-fallback='true']
optional

Specifies behavior if the target selector is missing from the current page or the server response.

If set to a CSS selector, Unpoly will attempt to replace that selector instead.

If set to true, Unpoly will attempt to replace a main target instead.

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

[up-match='region']
optional

Controls which fragment to update when the [up-target] selector yields multiple results.

When set to 'region' Unpoly will prefer to update fragments in the region of the origin element.

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

Defaults to up.fragment.config.match, which defaults to 'region'.

[up-use-hungry='true']
optional

Whether [up-hungry] elements outside the updated fragment will also be updated.

Navigation

[up-navigate='true']
optional

Whether this fragment update is considered navigation.

Setting this to false will disable most defaults documented below, causing Unpoly to render a fragment without side-effects like updating history or scrolling.

Request

action
required

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

method
required

The HTTP method to use for the request.

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.

[up-params]
optional

Additional Form parameters that should be sent as the request's query string or payload.

The given value will be added to params parsed 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.

[up-headers]
optional

A relaxed JSON object with additional request headers.

Unpoly will by default send a number of custom request headers. E.g. the X-Up-Target header includes the target selector. See up.protocol for details.

[up-abort='target']
optional

Whether to abort existing requests before rendering.

[up-abortable='true']
optional

Whether this request may be aborted by other requests targeting the same fragments or layer.

See aborting requests for details.

[up-background='false']
optional

Whether this request will load in the background.

Background requests deprioritized over foreground requests. Background requests also won't emit up:network:late events and won't trigger the progress bar.

[up-late-delay]
optional

The number of milliseconds after which this request can cause an up:network:late event.

Defaults to up.network.config.lateDelay.

[up-timeout]
optional

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

Defaults to up.network.config.timeout.

Layer

[up-layer='origin, current']
optional

The layer in which to match and render the fragment.

See layer option for a list of allowed values.

To open the fragment in a new overlay, pass [up-layer=new]. In this case attributes for [up-layer=new] may also be used.

[up-fail-layer='origin, current']
optional

The layer in which render if the server responds with an error code.

See Rendering failed responses differently.

[up-peel='true']
optional

Whether to close overlays obstructing the updated layer when the fragment is updated.

This is only relevant when updating a layer that is not the frontmost layer.

History

[up-history='auto']
optional

Whether the browser URL, window title and meta tags will be updated.

If set to true, the history will always be updated, using the title and URL from the server response, or from given [up-title] and [up-location] attributes.

If set to auto history will be updated if the [up-target] matches a selector in up.fragment.config.autoHistoryTargets. By default this contains all main targets.

If set to false, the history will remain unchanged.

See Updating history.

[up-fail-history='auto']
optional

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

See Rendering failed responses differently.

[up-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, set [up-title=false] to explicitly

This attribute is only used when updating history.

[up-location]
optional

An explicit URL to set before rendering.

By default Unpoly will use the link's [href] or the final URL after the server redirected. To prevent the URL from being updated, set [up-location=false].

This attribute is only used when updating history.

[up-meta-tags]
optional

Whether to update meta tags in the <head>.

By default Unpoly will extract meta tags from the response's <head>. To prevent meta tags from being updated, set [up-meta-tags=false].

This attribute is only used when updating history.

[up-lang]
optional

An explicit language code to set as the html[lang] attribute.

By default Unpoly will extract the language from the response and update the html[lang] attribute in the current page. To prevent the attrribute from being changed, set [up-lang=false].

This attribute is only used when updating history.

Animation

[up-transition]
optional

The name of an transition to morph between the old and few fragment.

If you are prepending or appending content, use the [up-animation] attribute instead.

[up-animation]
optional

The name of an animation to reveal a new fragment when prepending or appending content.

If you are replacing content (the default), use the [up-transition] attribute instead.

[up-duration]
optional

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

[up-easing]
optional

The timing function that accelerates the transition or animation.

See MDN documentation for a list of available timing functions.

Caching

[up-cache='auto']
optional

Whether to read from and write to the cache.

With [up-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. If no cached response exists, Unpoly will make a request and cache the server response.

With [up-cache=auto] Unpoly will use the cache only if up.network.config.autoCache returns true for the request. By default this only caches GET requests.

With [up-cache=false] Unpoly will always make a network request.

[up-revalidate='auto']
optional

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

With [up-revalidate='auto'] Unpoly will revalidate expired responses.
This behavior can be configured with up.fragment.config.autoRevalidate(response).

With [up-revalidate='true'] Unpoly will always revalidate cached content, regardless of its age.

With [up-revalidate='false'] Unpoly will never revalidate cached content.

[up-revalidate-preview]
optional

The name of a preview that runs while revalidating cached content.

[up-expire-cache]
optional

Whether existing cache entries will be expired with this request.

By default a non-GET request will expire the entire cache. You may also pass a URL pattern to only expire matching requests.

Also see up.request({ expireCache }) and up.network.config.expireCache.

[up-evict-cache]
optional

Whether existing cache entries will be evicted with this request.

You may also pass a URL pattern to only evict matching requests.

Also see up.request({ evictCache }) and up.network.config.evictCache.

Scrolling

[up-scroll='auto']
optional

How to scroll after the new fragment was rendered.

See Scrolling for a list of allowed values.

[up-fail-scroll='auto']
optional

How to scroll after the new fragment was rendered from a failed response.

See Rendering failed responses differently.

[up-scroll-behavior='instant']
optional
[up-reveal-snap]
optional

When to snap to the top when scrolling to an element near the top edge of the viewport's scroll buffer.

[up-reveal-top]
optional

When to move a revealed element to the top when scrolling to an element.

[up-reveal-padding]
optional

How much space to leave to the closest viewport edge when scrolling to an element.

[up-reveal-max]
optional

How many pixel lines of high element to reveal when scrolling to an element.

[up-save-scroll='true']
optional

Whether to save scroll positions before updating the fragment.

Saved scroll positions can later be restored with [up-scroll=restore].

Focus

[up-focus='auto']
optional

What to focus after the new fragment was rendered.

See Controlling focus for a list of allowed values.

[up-fail-focus='auto']
optional

What to focus after the new fragment was rendered from a failed response.

See Rendering failed responses differently.

[up-focus-visible='auto']
optional

Whether the focused element should have a visible focus ring.

By default focus will be visible if up.viewport.config.autoFocusVisible() returns true for the focused element and current input device.

[up-save-focus='true']
optional

Whether to save focus-related state before updating the fragment.

Saved scroll positions can later be restored with [up-focus=restore].

Loading state

[up-disable]
optional

Disables form controls while the request is loading.

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

[up-placeholder]
optional

A placeholder to show in the targeted fragment while new content is loading.

Existing children of the targeted fragment will be hidden during the request. When the request ends for any reason, all changes will be reverted.

You can either pass a HTML string or refer to a template, optionally with variables.

If this link opens a new overlay, the placeholder will be shown temporary overlay with the same visual style and open animation.

[up-preview]
optional

The name of a preview that temporarily changes the page while new content is loading.

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

[up-feedback='true']
optional

Whether to set feedback classes while loading content.

Client state

[up-use-data]
optional

A relaxed JSON object that overrides properties from the new fragment's data.

[up-use-keep='true']
optional

Whether [up-keep] elements will be preserved in the updated fragments.

[up-context]
optional

A relaxed JSON object that will be merged into the context of the current layer once the fragment is rendered.

Lifecycle hooks

[up-confirm]
optional

A message the user needs to confirm before any request or changes are made.

The message will be shown as a native browser prompt.

If the user does not confirm, no request is sent and no fragments are updated.

[up-on-loaded]
optional

A JavaScript snippet that is executed when the server responds with new HTML, but before the HTML is rendered.

The snippet runs in the following scope:

Expression Value
this The link being followed
event A preventable up:fragment:loaded event

The snippet will also run for failed responses.

[up-on-offline]
optional

A JavaScript snippet that is executed when the fragment could not be loaded due to a disconnect or timeout.

Expression Value
this The link being followed
error An up.Offline error
[up-on-rendered]
optional

A JavaScript snippet that is executed when Unpoly has updated fragments.

The snippet runs in the following scope:

Expression Value
this The link being followed
result The up.RenderResult for the respective render pass

The snippet will be called zero, one or two times:

  • When the server rendered an empty response, no fragments are updated. [up-on-rendered] is not called.
  • When the server rendered a matching fragment, it will be updated on the page. [up-on-rendered] is called with the result.
  • When revalidation renders a second time, [up-on-rendered] is called again with the final result.

Also see Running code after rendering.

[up-on-finished]
optional

A JavaScript snippet that is executed when no further DOM changes will be caused by this render pass.

In particular:

Expression Value
this The link being followed
result The up.RenderResult for the last render pass that updated a fragment

If revalidation re-rendered the fragment, result describes updates from the second render pass. If no revalidation was performed, or if revalidation yielded an empty response, it is the result from the initial render pass.

Also see Awaiting postprocessing.

[up-on-error]
optional

A JavaScript snippet that is run when any error is thrown during the rendering process.

Expression Value
this The link being followed
error An Error object

The callback is also called when the render pass fails due to network issues, or aborts.

Also see Handling errors.