HTML Form Persistence

A simple library for preserving form values across page refreshes and multiple sessions.

Installation

npm install form-persistence

import FormPersistence from 'form-persistence';

Or include the script hosted on jsDelivr CDN or download and link the script directly.

<script src='https://cdn.jsdelivr.net/gh/FThompson/FormPersistence.js@2.0.6/form-persistence.min.js'></script>

Usage

The FormPersistence module's main function is FormPersistence.persist, which persists a form across refreshes or sessions.

let form = document.getElementById('test-form');
FormPersistence.persist(form);

FormPersistence.persist loads saved form data into the form and sets up event handlers that take care of saving form data. By default, form data is saved to local storage and cleared upon form submission.

Ensure that you call persist after the document has finished loading, either by using an onLoad event handler or by adding defer to the script import.

What if my form has complex elements that require custom data loading?

If your form has elements that are added to the page depending on selected data, you can set up custom value functions that are invoked when loading data into the persisted form. These functions are passed in the options object parameter. Other options include uuid, useSessionStorage, saveOnSubmit, include, exclude, includeFilter, and excludeFilter. See details in the below API reference.

The valueFunctions parameter takes a dictionary object where the keys are form data names and the values are functions that handle loading in the values for those data names.

let formValueFunctions = {
    name: callback(form, value)
};

Custom Value Functions Example

Consider a post submission form that takes a title, a post body, and a set of tags describing the post.

<form id='create-post'>
    <div>
        <label for='title'>Title</label>
        <input type='text' name='title' id='title'>
    </div>
    <div>
        <label for='post-body'>Body</label>
        <textarea name='post-body' id='post-body'></textarea>
    </div>
    <div>
        <label for='tags'>Tags</label>
        <input type='text' id='tag-input'><button type='button' id='add-tag'>Add</button>
        <div id='added-tags'></div>
    </div>
    <input type='submit'>
</form>

You want users to be able to remove tags they have added, so you create a script that adds a span with each selected tag and a button to remove that tag. You add tags to the form's data as span elements each containing a hidden input element containing the tag to be submitted in the form's data.

document.getElementById('add-tag').addEventListener('click', addTag);
 
function addTag() {
    let tagsBox = document.getElementById('tag-input');
    createTag(tagsBox.value);
    tagsBox.value = '';
}
 
function createTag(tag) {
    let tagsDiv = document.getElementById('added-tags');
    let tagElement = document.createElement('span');
    tagElement.textContent = tag;
    tagsDiv.appendChild(tagElement);
    let removeElement = document.createElement('a');
    removeElement.textContent = '\u274c';
    removeElement.addEventListener('click', () => tagsDiv.removeChild(tagElement));
    tagElement.appendChild(removeElement);
    let tagValue = document.createElement('input');
    tagValue.setAttribute('type', 'hidden');
    tagValue.setAttribute('name', 'tag');
    tagValue.value = tag;
    tagElement.appendChild(tagValue);
}

If you try to set up form persistence normally on this form, the script would not create the tag because the script would unable to find any inputs named tag in the document. This scenario requires custom value functions.

let valueFunctions = {
    'tag': (form, value) => createTag(value)
};

Pass the value functions to FormPersistence.persist.

FormPersistence.persist(form, { valueFunctions: valueFunctions });

Voila! The persist function will now create tag elements upon loading the form's persisted data.

See the complete working example here. Change form values and refresh the page to observe persistence.

API Reference

FormPersistence.persist(form[, options])

Register a form for persistence. Values are saved to local or session storage on page refresh and optionally on form submission. Defaults to use local storage and clear form data on submit. Calling this function loads saved data into the form.