Forms with an
up-target attribute are submitted via AJAX
instead of triggering a full page reload.
<form method="post" action="/users" up-target=".main"> ... </form>
The server response is searched for the selector given in
The selector content is then replaced in the current page.
The programmatic variant of this is the
When the server was unable to save the form due to invalid data, it will usually re-render an updated copy of the form with validation messages.
For Unpoly to be able to detect a failed form submission, the form must be re-rendered with a non-200 HTTP status code. We recommend to use either 400 (bad request) or 422 (unprocessable entity).
In Ruby on Rails, you can pass a
:status option to
class UsersController < ApplicationController def create user_params = params[:user].permit(:email, :password) @user = User.new(user_params) if @user.save? sign_in @user else render 'form', status: :bad_request end end end
Note that you can also use
input[up-validate] to perform server-side
validations while the user is completing fields.
Unpoly requires an additional response headers to detect redirects, which are otherwise undetectable for an AJAX client.
After the form's action performs a redirect, the next response should echo
the new request's URL as a response header
If you are using Unpoly via the
unpoly-rails gem, these headers
are set automatically for every request.
<form> element will be assigned a CSS class
the submission is loading.
The selector to replace if the form submission is successful (200 status code).
The selector to replace if the form submission is not successful (non-200 status code).
If omitted, Unpoly will replace the
<form> tag itself, assuming that the
server has echoed the form with validation errors.
The selector to replace if the server responds with a non-200 status code.
The animation to use when the form is replaced after a successful submission.
The animation to use when the form is replaced after a failed submission.
Whether to push a browser history entry after a successful form submission.
By default the form's target URL is used. If the form redirects to another URL, the redirect target will be used.
Set this to
'false' to prevent the URL bar from being updated.
Set this to a URL string to update the history with the given URL.
The HTTP method to be used to submit the form (
Alternately you can use an attribute
method (vanilla HTML) for the same purpose.
The name of the layer that ought to be updated. Valid values are
If set to
auto (default), Unpoly will try to find a match in the form's layer.
If no match was found in that layer,
Unpoly will search in other layers, starting from the topmost layer.
The name of the layer that ought to be updated if the server sends a non-200 status code.
Whether to reveal the target element within its viewport before updating.
Whether to restore previously known scroll position of all viewports within the target selector.
Whether to force the use of a cached response (
or never use the cache (
or make an educated guess (
By default only responses to
GET requests are cached for a few minutes.