saveform

Lightweight solution to persist form field values across page reloads

Automatically save HTML form field values to localStorage or sessionStorage and restore them when the user returns to the page.

• Tiny footprint (~2KB minified and gzipped)
• No dependencies
• Modern ESM format
• Works with all form elements (input, select, textarea, etc.)
• Flexible field selection/exclusion
• Custom storage triggers (input, change, or both)
• Support for custom value accessors and setters
• Configurable storage key prefix

Installation

Add this to your script:

import saveform from "saveform";

To use via CDN, add this to your HTML file:

<script type="importmap">
  {
    "imports": {
      "saveform": "https://cdn.jsdelivr.net/npm/saveform@1"
    }
  }
</script>

To use locally, install via npm:

npm install saveform

... and add this to your HTML file:

<script type="importmap">
  {
    "imports": {
      "saveform": "./node_modules/saveform/dist/saveform.min.js"
    }
  }
</script>

Usage

// One-liner: automatically save & restore form values with default settings
import saveform from "saveform";
saveform("#my-form");

// With options
saveform("#my-form", {
  storage: sessionStorage, // use sessionStorage instead of localStorage
  prefix: "myapp_", // prefix for storage keys. Default: "saveform_"
  events: ["change"], // only save on change events
});

On any form change, this persists all fields that have a name="..." or an id="..." in sessionStorage (default: localStorage) as a JSON object with the key ${prefix}${formId}, e.g. myapp_my-form. formId is the form's id= else name= else a random key.

By default, type="password" and type="file" fields are excluded. To include password fields, use:

saveform("#my-form", { exclude: '[type="file"]' });

API

saveform(element, options)

Creates a new saveform instance and immediately restores any saved values.

element

Type: HTMLElement | string

The form element or selector string.

options

Type: Object

| Option | Type | Default | Description | | ----------- | ---------------------- | ------------------------------------ | ------------------------------------ | | storage | Storage | localStorage | Storage mechanism to use | | prefix | string | 'saveform_' | Prefix for storage keys | | events | string[] | ['input', 'change'] | Events that trigger saving | | fields | string | Function | '*' | Fields to include (* includes all) | | exclude | string | Function | '[type="password"], [type="file"]' | Fields to exclude | | dropEmpty | boolean | false | Delete (reset) key if value is "" | | accessors | Object | {} | Custom value getters | | setters | Object | {} | Custom value setters |

Methods

Each saveform instance returns an object with these methods:

save()

Manually save current form values.

const form = saveform("#my-form");
form.save();

save() merges the current form values with any data already in storage. This ensures values from fields that were removed from the DOM (for example, in dynamic forms) remain intact.

restore()

Manually restore saved values.

form.restore();

clear()

Clear all saved values.

form.clear();

destroy()

Remove all event listeners and stop tracking.

form.destroy();

Field Selection

Control which fields are saved:

// Only save text and email inputs
saveform("#my-form", {
  fields: 'input[type="text"], input[type="email"]',
});

// Exclude specific fields
saveform("#my-form", {
  exclude: ".sensitive, [data-no-save]",
});

// Use functions for complex logic
saveform("#my-form", {
  fields: (field) => field.dataset.save === "true",
  exclude: (field) => field.name.startsWith("private_"),
});

Reset saved values

dropEmpty: true lets users revert to the page default by clearing a field.

// Allow user to reset saved valued
saveform("#my-form", { dropEmpty: true });

Custom Value Handlers

Define custom ways to get/set values:

saveform("#my-form", {
  accessors: {
    // Custom getter for tag inputs (comma-separated values)
    ".tag-input": (field) => field.value.split(",").map((t) => t.trim()),

    // Get selected options from multi-select
    "select[multiple]": (field) => Array.from(field.selectedOptions).map((opt) => opt.value),
  },

  setters: {
    // Custom setter for tag inputs
    ".tag-input": (field, value) => (field.value = Array.isArray(value) ? value.join(", ") : value),
  },
});

Development

git clone https://github.com/sanand0/saveform.git
cd saveform

npm install
npm run lint && npm run build && npm test

npm publish
git commit . -m"$COMMIT_MSG"; git tag $VERSION; git push --follow-tags

Release notes

• 1.4.0: 29 Sep 2025. Add dropEmpty option that resets empty fields to page default
• 1.3.1: 31 Jul 2025. Standardized package.json & README.md, move saveform.min.js into dist/
• 1.2.2: 05 Jun 2025. Document how to save password / hidden fields, expand test coverage
• 1.2.0: 22 May 2025. Fall back to id attribute if name is missing
• 1.1.1: 21 May 2025. Renamed "all" option to "*". Added tests and docs
• 1.0.0: 21 May 2025. Initial release

License

MIT