Offline mode for forms

Form.io’s offline mode allows your application to render forms, accept submissions, and queue data locally when users have no internet connection. When connectivity returns, the queued submissions sync to your Form.io server automatically. The user experience remains consistent whether online or offline: they fill out a form, click submit, and the data is captured.

This is not a graceful degradation where forms simply fail to load. The offline plugin caches form definitions locally, renders them from that cache when the network is unavailable, stores submissions in the browser’s IndexedDB, and manages a queue that processes when the connection is restored.

How Offline Mode Works

The Form.io offline plugin intercepts API requests made by the form renderer. When the application detects a network failure, requests that would normally go to your Form.io API server are redirected to local browser storage instead.

The system operates in two stages. First, it caches form definitions so forms can render without fetching from the server. Second, it queues submissions locally and processes that queue when connectivity returns.

Here is the basic flow:

  1. Your application loads while online and caches form JSON schemas to IndexedDB
  2. User goes offline (enters a rural area, loses signal, works in a basement)
  3. User opens a form, which renders from the local cache
  4. User submits the form, which is stored in the offline queue
  5. The submission appears successful to the user
  6. When connectivity returns, the queue processes and submissions sync to the server

The queue is first-in, first-out. Submissions sync in the order they were made. If a submission fails during sync (for example, server-side validation rejects it), the queue stops and your application must handle the error before continuing.

What Offline Mode Requires

Offline mode is not a configuration toggle. It requires the Form.io Offline Plugin, which is a licensed add-on that your development team integrates into your application.

Technical requirements:

  • A Library License with offline mode enabled
  • The @formio/offline-plugin npm package installed in your application
  • Browser support for IndexedDB (all modern browsers: Chrome 38+, Safari 7.1+, Firefox 13+, IE 11+)
  • Developer implementation of queue error handling

What your developers must build:

  • Integration of the offline plugin with your application
  • Logic to handle submission queue errors (validation failures, conflicts)
  • UI to show users their offline/online status and pending submission count
  • Decisions about which forms should be cached for offline use

This is infrastructure that enables offline capability. Your team builds the user experience around it. See Why You Should Not Use Form.io If You Do Not Have a Dev Team for context on the development resources required for Form.io projects.

Setting Up Offline Mode

The offline plugin registers with Form.io’s module system and attaches to a specific project. Here is the basic setup:

import { Formio } from '@formio/js';
import { OfflinePlugin } from '@formio/offline-plugin';

Formio.license = 'yourLibraryLicenseKey';
Formio.setBaseUrl('https://yourserver.com');
Formio.setProjectUrl('https://yourserver.com/yourproject');

Formio.use(OfflinePlugin(
  'myproject-offline',
  'https://yourserver.com/yourproject',
  'path/to/project.json',
  {}
));

The project.json parameter is optional but important. If you provide an exported copy of your project’s form definitions, the application can render forms even if the user has never been online. Without it, forms must be loaded online at least once before they are available offline.

For field data collection scenarios where users may start their day without connectivity, pre-loading the project JSON ensures forms are always available.

Caching Forms for Offline Use

Forms are cached automatically when loaded online. If your application calls formio.loadForm() while connected, that form schema is stored in IndexedDB and available for offline rendering.

For applications where specific forms must always be available offline, load them during initialization:

const formio = new Formio('https://yourserver.com/yourproject/inspection');
formio.loadForm(); // Caches the form for offline use

You can also pre-load submissions for reference:

formio.loadSubmissions(); // Caches existing submissions for offline viewing

This is useful when field workers need to review previous entries, look up reference data, or continue editing draft submissions while offline.

The JSON-driven architecture that Form.io uses makes this caching efficient. Form definitions are JSON schemas, typically a few kilobytes each. Your application can cache dozens of forms without significant storage impact.

The Submission Queue

When a user submits a form while offline, the submission goes into a local queue rather than to the server. The queue persists in IndexedDB, so it survives browser restarts and device reboots.

From the user’s perspective, the submission succeeds. The form clears, any success message displays, and they can continue working. The actual server sync happens later, transparently.

Your application can check the queue status:

const offlinePlugin = Formio.getPlugin('myproject-offline');
const pendingCount = offlinePlugin.submissionQueueLength();
console.log(`${pendingCount} submissions waiting to sync`);

This lets you build UI that shows users how many submissions are pending, giving them confidence that their work is saved.

When connectivity returns, you can process the queue manually:

offlinePlugin.dequeueSubmissions();

Or let it process automatically when the next online submission occurs.

Handling Sync Errors

The queue processes submissions in order. If a submission fails during sync, the queue stops. This prevents data integrity issues where later submissions might depend on earlier ones.

Common failure scenarios:

  • Server-side validation failure: A required field passed client-side validation but fails a server-side rule
  • Unique constraint violation: The submission conflicts with data that was created while the user was offline
  • Authentication expiration: The user’s session expired during the offline period
  • Resource reference failure: The submission references a resource that was deleted

Your application must handle these errors. The offline plugin emits events you can listen for:

Formio.events.on('offline.formError', (error) => {
  // Show error to user, allow them to fix or skip the submission
});

Formio.events.on('offline.formSubmission', (submission) => {
  // Submission synced successfully
});

Formio.events.on('offline.queueEmpty', () => {
  // All pending submissions have synced
});

When an error occurs, you have two options: fix the submission and retry, or skip it and continue with the rest of the queue.

// Fix and retry
const badSubmission = offlinePlugin.getNextQueuedSubmission();
badSubmission.data.requiredField = 'corrected value';
offlinePlugin.setNextQueuedSubmission(badSubmission);
offlinePlugin.dequeueSubmissions();

// Or skip and continue
offlinePlugin.skipNextQueuedSubmission();
offlinePlugin.dequeueSubmissions();

This error handling is not optional. If your application does not implement it, failed submissions will block the queue indefinitely. Users will not understand why their new submissions are not syncing.

What Does Not Work Offline

Offline mode has limitations. Understanding them helps you design appropriate user experiences.

Authentication does not work offline. If your forms require login, users must authenticate while online. The offline plugin cannot validate credentials against your server. For field data collection, this typically means users log in at the start of their day while they have connectivity, then work offline with that session.

Server-side actions do not execute. Webhooks, email notifications, and other server-side actions configured on your forms only trigger when submissions actually reach the server. If a user submits offline, those actions queue along with the submission.

Calculated fields that depend on server data may be stale. If your form pulls in data from other resources or external APIs, that data reflects what was cached, not current server state.

File uploads require special handling. Large file uploads while offline can consume significant local storage. Your application should account for storage limits and potentially restrict file sizes for offline submissions.

Real-time features are unavailable. Submission data webhooks and live updates obviously require connectivity.

Use Cases for Offline Forms

Offline mode solves specific problems. It is not universally needed, but for certain applications it is essential.

Field inspections and audits. Inspectors visiting job sites, construction projects, or remote facilities often work in areas with poor cellular coverage. They need to complete inspection forms regardless of connectivity and sync when they return to the office or reach a coverage area.

Healthcare in rural or underserved areas. Community health workers, mobile clinics, and home health visits frequently occur where internet access is unreliable. Patient intake forms, assessments, and visit documentation must work offline.

Agriculture and natural resources. Farm inspections, forestry surveys, water quality sampling, and wildlife monitoring happen in remote locations. Field researchers cannot depend on cellular coverage.

Disaster response. Emergency situations often involve damaged infrastructure. First responders and relief workers need to collect data in areas where networks are down.

Industrial and manufacturing. Factory floors, warehouses, and industrial facilities sometimes have poor wireless coverage due to building construction or interference. Equipment inspections and safety checklists must work regardless.

Events and conferences. Large gatherings can overwhelm local cellular infrastructure. Registration forms, surveys, and lead capture should not depend on network availability.

If your users work primarily at desks with reliable internet, you probably do not need offline mode. If your users work in the field, travel to remote locations, or operate in environments where connectivity is unreliable, offline mode may be essential to your application’s success.

Offline Mode and Progressive Web Apps

Form.io’s offline capability integrates well with Progressive Web App (PWA) architecture. PWAs use service workers to cache application assets and provide offline functionality at the application level. Form.io’s offline plugin handles the data layer: caching form definitions and queuing submissions.

Together, they enable applications that:

  • Install to the device home screen without an app store
  • Load instantly from cache, even without network
  • Render and submit forms offline
  • Sync data when connectivity returns

This is particularly valuable for field data collection where you want a native app experience without the overhead of building and distributing separate iOS and Android applications. Your web application, built with Form.io forms embedded, can function as a fully offline-capable mobile app.

The form renderer works identically whether forms load from the server or from the offline cache. Your application code does not need to differentiate between online and offline states for basic form rendering and submission.

Offline Mode vs. Auto-Save

Offline mode and auto-save forms solve different problems and can be used together.

Auto-save periodically saves form progress to your server while the user is filling out a long form. If they close the browser or navigate away, they can return and continue where they left off. Auto-save requires connectivity to work.

Offline mode allows form submission when there is no connectivity. The submission queues locally and syncs later.

For field data collection, you might use both: auto-save to protect against accidental data loss when online, and offline mode to handle periods without connectivity. The offline plugin can be configured to skip the queue for auto-save operations, sending them directly to the server when possible:

formio.saveSubmission(submission, { skipQueue: true });

This prevents auto-save drafts from clogging the offline queue while still allowing manual submissions to queue when offline.

Testing Offline Functionality

Before deploying an application with offline mode, test it thoroughly. Browser developer tools allow you to simulate offline conditions:

  1. Open your browser’s developer tools
  2. Go to the Network tab
  3. Select “Offline” from the throttling dropdown
  4. Use your application and submit forms
  5. Check IndexedDB storage to verify submissions are queued
  6. Return to online mode and verify submissions sync

Test the error scenarios too. Submit data that will fail server validation and verify your error handling works correctly. Test what happens when the user’s session expires during an offline period.

Field testing is also essential. Simulated offline in a browser is not identical to actual loss of cellular signal. If possible, test in conditions similar to where your users will actually work.

Documentation

Related Features