Web Storage stores string keys and values in the browser. Use it for small settings that are cheap to serialize and restore, such as a theme choice or dismissed banner—not as an application database. section 12.4.4
Table 12.2 Choosing a browser storage API
| API | Use it for | Avoid it for |
Local Storage |
Small preferences, flags, and last-used UI state represented as strings. |
Large objects, high-frequency writes, or structured offline data. |
Session Storage |
Temporary tab/session state that should survive reloads but not become long-term data. |
Anything where "session" needs a precise mobile or cross-browser meaning. |
IndexedDB |
Structured application data, offline records, drafts, queues, and blobs. |
HTTP responses or files that should be naturally addressed by URL. |
Cache Storage |
Request/response pairs and cached network resources. |
General business objects that are not naturally identified by a URL. |
File System Access API |
User-chosen files such as documents, exports, and editors. |
Cross-browser application state or silent background persistence. |
Origin Private File System (OPFS) |
Origin-private files and byte-oriented storage, often for complex editors, databases, or WebAssembly-backed tools. |
User-visible documents that should live in the user’s real file system. |
Compare storage APIs by data shape and use: Web Storage suits small string values, while structured records, network responses, and files have other browser-native options. section 12.4.2
Both localStorage and sessionStorage provide a small key/value interface. localStorage persists across browser sessions; sessionStorage lasts across reloads within a browsing session, whose meaning can vary on mobile and embedded clients. section 12.4.4
const preferences = JSON.parse(
localStorage.getItem("preferences") ?? "{}"
);
preferences.theme = "dark";
localStorage.setItem(
"preferences",
JSON.stringify(preferences)
);
Objects require explicit JSON parsing and serialization; keep stored values small and avoid frequent writes such as autosaving on every keystroke. section 12.4.4
Account for these operational limits:
- Reads and writes are synchronous and can block the main thread; Web Storage is unavailable in workers and service workers. section 12.4.4
- The storage event fires in other same-origin browsing contexts, not in the tab that made the change. section 12.4.4
- Choose IndexedDB for structured data, larger quotas, asynchronous access, worker access, or offline records. section 12.4.4
window.addEventListener("storage", (event) => {
if (event.key === "preferences") {
applyPreferences(JSON.parse(event.newValue ?? "{}"));
}
});
Listen for storage events to react to preference changes made in another same-origin tab. section 12.4.4


