Persist and restore Angular form state (values + simple meta) with an easy directive and service.
npm install ng-form-saver
Lightweight Angular utility that persistently saves form state (values + simple meta like dirty/touched) to storage (default: localStorage) and restores it on attach. Designed to work with both Reactive Forms and Template-driven Forms (ngForm). Useful for long forms, multi-step forms, or protecting user input across reloads and navigation.
This README documents the public API, configuration, examples, SSR notes, and common use-cases.
Supported Angular versions: 20.x and up
- Features
- Installation
- Quick Start
- Template-driven Forms
- Directive Input Variants
- On-Demand Save
- Programmatic API
- Options
- Default Provider
- Migrations
- TTL (Time to Live)
- Custom Storage
- Use-cases
- SSR Notes
- API Reference
- Troubleshooting
- Contributing
- License
- ✅ Automatically persist form values and basic meta (dirty/touched)
- ✅ Works with Reactive Forms (FormGroup, FormArray) and template-driven NgForm
- ✅ On-demand save — manually trigger save via handle output or programmatic API
- ✅ Configurable debounce, storage backend, and key-generation
- ✅ Supports migrations via a simple migrate API for evolving saved shapes
- ✅ TTL (Time to Live) support for automatic data expiration
- ✅ Custom storage backends (sessionStorage, IndexedDB, API, etc.)
- ✅ SSR-safe with automatic fallback to in-memory storage
- ✅ Standalone-friendly and includes a provideFormSaver helper to set defaults
Install from npm:
``bash`
npm install ng-form-saver
Or with yarn:
`bash`
yarn add ng-form-saver
Or with pnpm:
`bash`
pnpm add ng-form-saver
During development inside this workspace you can run the host demo application. From the workspace root:
`bash`
npm install
npm start
- Open http://localhost:4200/demo to view the demo form.
To build the library itself:
`bash`
ng build ng-form-saver
To publish (after build):
`bash`
cd dist/ng-form-saver
npm publish
1. Import the library symbols from the published package (or for local dev you may import from the project path):
2. Use the formSaver directive on a form. The simplest usage is to provide a string key.
Template example:
`html`
Component setup (minimal):
`ts
import { FormGroup, FormControl } from "@angular/forms";
profileForm = new FormGroup({
name: new FormControl(""),
email: new FormControl(""),
});
`
That’s it — the directive will persist the form value to localStorage under key profile-form and will patch the control with saved values when attached.
`html`
The directive detects the active NgForm or FormGroupDirective automatically and will throw an error if no form control is present.
The directive accepts multiple input forms via the formSaver input binding:
- "my-key" — string key used in storagetrue
- / false — boolean shorthand (true means attach with defaults)''
- (empty) — attach with defaults (service will resolve key)Partial
- — options object
Example with options:
`html`
Instead of relying solely on debounced auto-save, you can manually trigger a save at any time using the formSaverHandle output. This is useful for:
- Save buttons that persist form state immediately
- Critical form actions where you want to ensure data is saved
- Forms with very long debounce times where immediate save is needed
`html
`
`typescript
import { Component } from "@angular/core";
import { FormGroup, FormControl, ReactiveFormsModule } from "@angular/forms";
import { FormSaverDirective, AttachHandle } from "ng-form-saver";
@Component({
selector: "app-checkout",
standalone: true,
imports: [ReactiveFormsModule, FormSaverDirective],
templateUrl: "./checkout.component.html",
})
export class CheckoutComponent {
checkoutForm = new FormGroup({
cardNumber: new FormControl(""),
expiry: new FormControl(""),
cvv: new FormControl(""),
});
private handle?: AttachHandle;
onHandleReady(handle: AttachHandle): void {
this.handle = handle;
console.log("Form saver attached with key:", handle.key);
}
saveNow(): void {
if (this.handle) {
this.handle.save(); // Immediately persist to storage
console.log("Form saved!");
}
}
clearSaved(): void {
this.handle?.clear(); // Remove from storage
}
}
`
The AttachHandle object provides these methods:
| Method | Description |
| ----------- | ------------------------------------------------- |
| save() | Immediately persist current form state to storage |clear()
| | Remove saved data from storage |destroy()
| | Stop auto-saving and clean up subscriptions |
| Property | Description |
| --------- | ----------------------------------------- |
| key | The resolved storage key |control
| | Reference to the attached AbstractControl |
You can attach programmatically to an AbstractControl (FormGroup, FormArray or FormControl) using FormSaverService.attach.
`ts
import { Component, OnDestroy } from "@angular/core";
import { FormGroup, FormControl } from "@angular/forms";
import { FormSaverService, AttachHandle } from "ng-form-saver";
@Component({
selector: "app-checkout",
standalone: true,
template: ...,
})
export class CheckoutComponent implements OnDestroy {
form = new FormGroup({
items: new FormControl([]),
coupon: new FormControl(""),
});
private handle: AttachHandle;
constructor(private saver: FormSaverService) {
this.handle = this.saver.attach(this.form, {
key: "checkout",
debounceTime: 200,
});
}
// On-demand save
saveProgress(): void {
this.handle.save();
}
// Clear saved data
clearCart(): void {
this.handle.clear();
}
ngOnDestroy(): void {
this.handle.destroy();
}
}
`
| Property/Method | Type | Description |
| --------------- | ----------------- | --------------------------------------------------- |
| key | string | Resolved storage key |control
| | AbstractControl | The control attached |save()
| | () => void | On-demand save — immediately persist form state |clear()
| | () => void | Remove saved payload from storage |destroy()
| | () => void | Unsubscribe from valueChanges and stop persisting |
| Property | Type | Default | Description |
| --------------- | ---------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | — | Storage key. If omitted and autoKey is true, key is derived from current route (requires Router). Otherwise defaults to 'form-saver'. |autoKey
| | boolean | false | Derive key from current route URL (requires Router in DI). |debounceTime
| | number | 300 | Debounce ms for valueChanges persistence. |version
| | number | — | Optional version identifier for saved payload. Works with migrations. |migrations
| | FormSaverMigration[] | [] | Array of migrations to bring old payloads forward. |clearOnSubmit
| | boolean | false | When true, the directive will clear the saved payload on ngSubmit. |storage
| | StorageLike | localStorage (fallback to in-memory) | Custom storage backend implementing getItem/setItem/removeItem. |ttl
| | number | — | Time to live in milliseconds. If set, saved data will automatically expire after this duration. |
`typescript
import { FormSaverOptions, FormSaverMigration } from "ng-form-saver";
const migrations: FormSaverMigration[] = [{ from: 1, to: 2, migrate: (data) => ({ ...data, updatedAt: Date.now() }) }];
const options: FormSaverOptions = {
key: "user-profile",
debounceTime: 500,
version: 2,
migrations,
clearOnSubmit: true,
ttl: 24 60 60 * 1000, // 24 hours
storage: localStorage,
};
`
The library exposes an injection token FORM_SAVER_DEFAULT_OPTIONS with defaults. Use provideFormSaver(defaults) to configure defaults for your app:
`ts
import { provideFormSaver } from "ng-form-saver";
bootstrapApplication(App, {
providers: [provideFormSaver({ debounceTime: 500, clearOnSubmit: true })],
});
`
This will change behavior of the directive and programmatic attach when a specific value isn't provided.
Saved payloads include an optional v field (version). To migrate older payloads to a new shape, pass migrations to options or via default provider. Each migration has from, to, and migrate(data).
Example migration:
`ts
const migrations = [{ from: 1, to: 2, migrate: (data) => ({ ...data, createdAt: Date.now() }) }];
this.saver.attach(this.form, { key: "profile", version: 2, migrations });
`
When a saved payload with v = 1 is found, the code above will apply the migrate function and set v to 2.
You can set an optional ttl (in milliseconds) to automatically expire saved form data after a certain duration. When the data expires, it will be cleared on the next restore attempt and the form will not be populated with stale data.
`html`
`ts`
// Form data expires after 30 minutes
const handle = this.saver.attach(this.form, {
key: "sensitive-form",
ttl: 30 60 1000, // 30 minutes in milliseconds
});
| Duration | Milliseconds |
| ---------- | ------------------------------------- |
| 5 minutes | 5 60 1000 (300000) |30 60 1000
| 30 minutes | (1800000) |60 60 1000
| 1 hour | (3600000) |24 60 60 * 1000
| 24 hours | (86400000) |7 24 60 60 1000
| 7 days | (604800000) |
Note: Expiration is checked only when restoring data. If the user has the form open continuously, the data will continue to be saved. The TTL resets on each save.
If you need to persist to a server or to sessionStorage or a cookie-backed storage, implement the StorageLike interface and pass it via options.
`typescript`
interface StorageLike {
getItem(key: string): string | null;
setItem(key: string, value: string): void;
removeItem(key: string): void;
}
`typescript`
// Use sessionStorage instead of localStorage
this.saver.attach(this.form, {
key: "session-form",
storage: sessionStorage,
});
`typescript
import { StorageLike } from "ng-form-saver";
class ApiStorage implements StorageLike {
private cache = new Map
getItem(key: string): string | null {
return this.cache.get(key) ?? null;
}
setItem(key: string, value: string): void {
this.cache.set(key, value);
// Async save to API
fetch("/api/form-state", {
method: "POST",
body: JSON.stringify({ key, value }),
headers: { "Content-Type": "application/json" },
});
}
removeItem(key: string): void {
this.cache.delete(key);
fetch(/api/form-state/${key}, { method: "DELETE" });
}
}
// Usage
const apiStorage = new ApiStorage();
this.saver.attach(this.form, { key: "synced-form", storage: apiStorage });
`
`typescript
import { StorageLike } from "ng-form-saver";
class IndexedDBStorage implements StorageLike {
private cache = new Map
constructor() {
// Load from IndexedDB on init
this.loadFromDB();
}
getItem(key: string): string | null {
return this.cache.get(key) ?? null;
}
setItem(key: string, value: string): void {
this.cache.set(key, value);
this.saveToDB(key, value);
}
removeItem(key: string): void {
this.cache.delete(key);
this.deleteFromDB(key);
}
private async loadFromDB(): Promise
// IndexedDB implementation...
}
private async saveToDB(key: string, value: string): Promise
// IndexedDB implementation...
}
private async deleteFromDB(key: string): Promise
// IndexedDB implementation...
}
}
`
- Long forms where users may accidentally navigate away or refresh
- Multi-step forms where intermediate state should persist across steps
- Admin dashboards with complex filters — preserve filter forms across sessions
- Offline/slow networks where saving to localStorage provides resilience
When rendering on the server, ensure your app bootstraps with a BootstrapContext forwarded to bootstrapApplication. Example server bootstrap (the library's demo app uses this pattern):
`ts
// src/main.server.ts
import { bootstrapApplication, BootstrapContext } from "@angular/platform-browser";
import { App } from "./app/app";
import { config } from "./app/app.config.server";
const bootstrap = (context: BootstrapContext) => bootstrapApplication(App, config, context);
export default bootstrap;
`
Also remember localStorage is not available on the server — the library falls back to an in-memory Map storage automatically.
| Export | Selector | Description |
| -------------------- | ------------- | ------------------------------------------------ |
| FormSaverDirective | [formSaver] | Attach to a