Form Persistence

Auto-Save & Data Recovery

Automatically save form data to browser storage and restore it when users return. Perfect for long forms, multi-step wizards, and improving user experience.

Auto-save

localStorage

Restoration

Basic Setup

Enable form persistence with a simple configuration to automatically save user data.

Enable form persistence by adding a persistence configuration to your form. The form data will be automatically saved as users type and restored when they return.

Basic Example

const { Form } = useFormedible({
  fields: [
    { name: 'firstName', type: 'text', label: 'First Name' },
    { name: 'lastName', type: 'text', label: 'Last Name' },
    { name: 'email', type: 'email', label: 'Email' },
  ],
  persistence: {
    key: 'user-registration-form',
    storage: 'localStorage',
    restoreOnMount: true
  }
});

Configuration Options

Customize persistence behavior with storage type, debouncing, and field exclusion.

Complete Configuration

persistence: {
  key: 'my-form-data',              // Unique storage key
  storage: 'localStorage',          // 'localStorage' or 'sessionStorage'
  debounceMs: 1000,                // Debounce save operations (default: 1000ms)
  exclude: ['password', 'ssn'],     // Fields to exclude from persistence
  restoreOnMount: true              // Restore data when component mounts
}

localStorage

Data persists across browser sessions until manually cleared. Best for forms users might return to later.

sessionStorage

Data persists only for the current browser session. Best for temporary data or sensitive forms.

Excluding Sensitive Fields

Prevent sensitive information from being saved to browser storage for security.

Use the exclude option to prevent sensitive fields from being saved to storage:

const { Form } = useFormedible({
  fields: [
    { name: 'username', type: 'text', label: 'Username' },
    { name: 'password', type: 'password', label: 'Password' },
    { name: 'creditCard', type: 'text', label: 'Credit Card' },
    { name: 'email', type: 'email', label: 'Email' },
  ],
  persistence: {
    key: 'registration-form',
    storage: 'localStorage',
    exclude: ['password', 'creditCard'], // These won't be saved
    restoreOnMount: true
  }
});

Manual Storage Control

Access storage functions directly for manual control over save, load, and clear operations.

Access storage functions directly for manual control over when data is saved or cleared:

const { 
  Form, 
  saveToStorage, 
  loadFromStorage, 
  clearStorage 
} = useFormedible({
  // ... configuration
});

// Manual operations
const handleSave = () => {
  const currentData = form.state.values;
  saveToStorage(currentData);
};

const handleLoad = () => {
  const savedData = loadFromStorage();
  if (savedData) {
    // Handle loaded data
    console.log('Loaded data:', savedData);
  }
};

const handleClear = () => {
  clearStorage();
};

Multi-Page Forms

Persistence automatically works with multi-step forms, saving both data and current page.

Persistence automatically works with multi-page forms, saving both form data and current page:

const { Form } = useFormedible({
  fields: [
    { name: 'firstName', type: 'text', label: 'First Name', page: 1 },
    { name: 'lastName', type: 'text', label: 'Last Name', page: 1 },
    { name: 'email', type: 'email', label: 'Email', page: 2 },
    { name: 'phone', type: 'tel', label: 'Phone', page: 2 },
  ],
  persistence: {
    key: 'multi-step-form',
    storage: 'localStorage',
    restoreOnMount: true
  }
});

// When user returns, they'll be on the same page with their data restored

Automatic Cleanup

Form data is automatically cleared from storage after successful form submission.

Form data is automatically cleared from storage when the form is successfully submitted:

const { Form } = useFormedible({
  fields: [
    // ... your fields
  ],
  persistence: {
    key: 'contact-form',
    storage: 'localStorage',
    restoreOnMount: true
  },
  formOptions: {
    onSubmit: async ({ value }) => {
      // Submit form data
      await submitToAPI(value);
      
      // Storage is automatically cleared after successful submission
      // No manual cleanup needed!
    }
  }
});

Error Handling

Graceful error handling ensures forms work even when storage operations fail.

Persistence operations are wrapped in try-catch blocks and will log warnings if storage fails:

// Storage operations handle errors gracefully
// If localStorage is full or disabled, the form continues to work normally
// Check browser console for persistence warnings

// You can also handle storage errors in your application:
const { Form, saveToStorage } = useFormedible({
  // ... configuration
});

const handleManualSave = () => {
  try {
    saveToStorage(form.state.values);
    console.log('Data saved successfully');
  } catch (error) {
    console.warn('Failed to save form data:', error);
    // Handle error (show user notification, etc.)
  }
};

Best Practices

Guidelines for effective persistence implementation and optimal user experience.

Unique Keys

Use descriptive, unique keys for each form to avoid conflicts between different forms.

Sensitive Data

Always exclude passwords, credit cards, and other sensitive information from persistence.

Storage Choice

Use localStorage for forms users might return to later, sessionStorage for temporary data.

Debouncing

Adjust debounce timing based on form complexity - longer for complex forms to reduce storage writes.

Ready to Implement Form Persistence?

Start building forms with automatic data persistence and recovery. Create resilient user experiences that never lose user progress.

Get Started View Examples