Plugins

What is a plugin?

@vuetils/form supports plugins to extend the functionality of a form. Plugins have acces to the entire Form instance and can therefore be used for example to:

• watch for value changes
• persist form state in local storage or a database
• manipulate the form state
• enable/disable form fields
• and much more

How to use a plugin?

Plugins can be added to a form in one of two ways. The easiest option is to pass the plugin to the useForm() function.

import { localStoragePlugin, useForm } from '@vuetils/form';

const form = useForm(
	{
		email: [''],
		password: [''],
	},
	{
		plugins: [localStoragePlugin('some-key')],
	}
);

The second option is to dynamically add a plugin with the addPlugin() function.

import { localStoragePlugin, useForm } from '@vuetils/form';

const form = useForm({
	email: [''],
	password: [''],
});

form.addPlugin(localStoragePlugin('some-key'));

Built-in Plugins

@vuetils/form comes with a set of built-in plugins that can be used out of the box.

Storage Plugin

The storage plugin persists the form's values on every value change. It also tries to restore the form state on initialization. For example, if a user has partially filled out a form and leaves and returns or refreshes the page, the form state is restored.

Internaly the plugin uses the Storage interface from the Web Storage API to set and get items to and form storage.

The plugin takes in an options object with 2 properties, a string key and a Storage object. The two storage types used in the browser are localStorage and sessionStorage but the plugin will work with any object implementing the Storage interface.

import { storagePlugin } from '@vuetils/form';

storagePlugin({ key: 'some-key', storage: localStorage });

For local and session storage @vuetils/form provides two helper plugin in localStoragePlugin and sessionStoragePlugin.

Local Storage Plugin

The local storage plugin is a wrapper around the storagePlugin with localStorage as the storage option.

import { localStoragePlugin } from '@vuetils/form';

localStoragePlugin('some-key');

Session Storage Plugin

The session storage plugin is a wrapper around the storagePlugin with sessionStorage as the storage option.

import { sessionStoragePlugin } from '@vuetils/form';

sessionStoragePlugin('some-key');

Write your own Plugin

The best part about plugins is that you can easily write your own. @vuetils/form comes with the helper function definePlugin that makes writing typesafe plugins a breeze.

definePlugin takes a callback function as its argument. This callback is passed the current Form instance and the plugin options as its arguments. If you pass a Type or Interface to definePlugin the options object will be correctly typed.

Your created plugin can be used like any other plugin, as described here.

import { definePlugin } from '@vuetils/form';

interface PluginOptions {
	// plugin options
}

const myPlugin = definePlugin<PluginOptions>((form, options) => {
	// do something with the form
});