Forms Plugin

A swup plugin for submitting forms.

• Serialize and submit forms with animated page transitions
• Opt-in with a configurable selector, by default form[data-swup-form]
• Respects custom animations set on the form element

Note: This plugin is perfect for simple scenarios like search or contact forms. For complex requirements like file uploads or custom serialization, it is recommended to use the swup API directly.

Installation

Install the plugin from npm and import it into your bundle.

npm install @swup/forms-plugin

npm install @swup/forms-plugin

import SwupFormsPlugin from '@swup/forms-plugin';

import SwupFormsPlugin from '@swup/forms-plugin';

Or include the minified production file from a CDN:

<script src="https://unpkg.com/@swup/forms-plugin@3"></script>

<script src="https://unpkg.com/@swup/forms-plugin@3"></script>

Usage

To run this plugin, include an instance in the swup options.

const swup = new Swup({
  plugins: [new SwupFormsPlugin()]
});

const swup = new Swup({
  plugins: [new SwupFormsPlugin()]
});

Server response

Action, method and encoding type attributes set on the form are respected.

The server response must be a valid page with all containers to be replaced by swup.

Custom animations

The plugin respects custom animations set on the form using the data-swup-animation attribute:

<!-- Animate with an 'overlay' custom animation -->
<form action="/" data-swup-form data-swup-animation="overlay">

<!-- Animate with an 'overlay' custom animation -->
<form action="/" data-swup-form data-swup-animation="overlay">

Options

formSelector

The formSelector option defines a selector for forms which should be sent via swup. By default, any form with a data-swup-form attribute is selected.

new SwupFormsPlugin({
  formSelector: 'form[data-swup-form]'
});

new SwupFormsPlugin({
  formSelector: 'form[data-swup-form]'
});

Hooks

The plugin adds two new hooks to swup.

form:submit

Triggered when a form is submitted.

swup.hooks.on('form:submit', (visit, { el, event }) => {
  console.log(el);
});

swup.hooks.on('form:submit', (visit, { el, event }) => {
  console.log(el);
});

form:submit:newtab

Triggered when a form is submitted to a new tab or window. This will happen if the user has pressed either the Command (Mac), Control (Windows) or Shift key while submitting the form. The plugin normalizes that behavior across browsers.