form-saver Web Component

A web component that stores (and restores) values within the first form it wraps.

It is designed for crash recovery and interrupted sessions:

• Saves form field values to localStorage as users type.
• Restores values when the page is loaded again.
• Clears saved values after a successful submit flow.
• Optionally retains selected fields after submit.

Demo

Live Demo (Source)

Additional demos:

• ESM CDN Demo (Source)
• Unpkg CDN Demo (Source)

Installation

npm install @aarongustafson/form-saver

Usage

Option 1: Auto-define the custom element (easiest)

Import the package to automatically define the <form-saver> custom element:

import '@aarongustafson/form-saver';

Or use the define-only script in HTML:

<script src="./node_modules/@aarongustafson/form-saver/define.js" type="module"></script>

Option 2: Import the class and define manually

Import the class and define the custom element with your preferred tag name:

import { FormSaverElement } from '@aarongustafson/form-saver/form-saver.js';

customElements.define('my-custom-name', FormSaverElement);

Basic Example

<form-saver>
  <form action="/contact" method="post">
    <label>
      Name
      <input name="name" autocomplete="name" />
    </label>
    <label>
      Email
      <input name="email" type="email" autocomplete="email" />
    </label>
    <button type="submit">Send</button>
  </form>
</form-saver>

The component targets the first descendant <form>.

Retain Selected Fields After Submit

Use retain to keep specific field names (or ids when name is missing) after submit:

<form-saver retain="name email">
  <form action="/contact" method="post">
    <input name="name" />
    <input name="email" type="email" />
    <textarea name="message"></textarea>
    <button type="submit">Send</button>
  </form>
</form-saver>

In this example, message is cleared after submit while name and email remain.

Let Users Control Retention

To inject an opt-in checkbox, add retain-choice.

<form-saver
  retain="name email"
  retain-choice
  retain-choice-label="Store my contact information for later"
>
  <form action="/contact" method="post">
    <input name="name" />
    <input name="email" type="email" />
    <button type="submit">Send</button>
  </form>
</form-saver>

By default, the checkbox is inserted just before the first submit control.

You can control placement with retain-choice-container, which accepts a CSS selector. The matched element is used as a container — the checkbox is appended inside it:

<form-saver
  retain="name email"
  retain-choice
  retain-choice-container=".retain-slot"
>
  <form action="/contact" method="post">
    <input name="name" />
    <input name="email" type="email" />
    <div class="retain-slot"></div>
    <button type="submit">Send</button>
  </form>
</form-saver>

Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | retain | string | "" | Space-separated field names (or ids when name is missing) to retain after successful submit | | retain-choice | boolean | false | Inject an opt-in retention checkbox | | retain-choice-label | string | "Store my contact information for later" | Plain-text label for the injected checkbox | | retain-choice-container | string | "" | CSS selector for a container element into which the checkbox is appended | | storage-key | string | derived | Optional storage key override |

Default derived storage key format:

form-saver:{method}:{resolvedActionUrl}

Where method and action come from the wrapped form.

Methods

| Method | Description | |--------|-------------| | saveFormState() | Serializes and persists current form values | | restoreFormState() | Applies saved values to current fields | | clearSavedData() | Removes saved values for the current form key |

Field Support

Supported controls include:

• input (except type="file", submit, button, reset, and image)
• textarea
• select (single and multiple)

File fields are intentionally excluded.

Browser Support

This component uses modern web standards:

• Custom Elements v1
• Light DOM (no shadow root)
• ES Modules

For older browsers, you may need polyfills.

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# View demo
open demo/index.html

License

MIT © Aaron Gustafson