JS localStorage Table
| Piece | What it does | Field note |
|---|---|---|
localStorage.setItem(k, v) | Persist strings | Strings ONLY - objects go through JSON (see the pairing below) |
localStorage.getItem(k) | Read (null if absent) | Missing key = null, not undefined - the falsy check that misleads |
localStorage.removeItem(k) | Delete one | No return value - idempotent on absent keys |
storage event | Cross-tab notify | Fires in OTHER tabs, not the writer - free multi-tab sync |
sessionStorage | Tab-scoped twin | Dies with the tab - drafts, wizards, per-tab state |
5MB quota | Strings as UTF-16 | QuotaExceededError on overflow - try/catch every setItem |
vs cookies | No expiry, no auto-send | Cookies ride every HTTP request; storage never leaves the browser |
vs IndexedDB | Sync + tiny vs async + big | Structured data and files go to IDB - storage is the key-value pocket |
Web storage is a synchronous string dictionary per origin: localStorage persists across reloads and browser restarts, sessionStorage dies with the tab, and both expose the same three methods - setItem, getItem, removeItem. Values are STRINGS ONLY; objects ride JSON.stringify on the way in and JSON.parse on the way out.
Bottom line: the storage event fires in every OTHER tab but never the writer - which makes cross-tab synchronization a one-liner (write in one tab, listen everywhere else). Quota overflow throws QuotaExceededError, so production setItem calls belong in try/catch, not just for politeness.
The honest part: storage never leaves the browser - no expiry, no automatic header. Cookies exist to ride HTTP requests; localStorage exists to stay local. And the 5MB quota counts strings as UTF-16, so non-ASCII data reaches the ceiling at half the character count you might expect.
How to use
- Persist state safely: localStorage.setItem('theme', JSON.stringify(theme)) with a matching JSON.parse(getItem(...)) - and try/catch the setItem for quota.
- Sync tabs for free: window.addEventListener('storage', e => applyTheme(e.newValue)) in every tab - the event carries key, oldValue and newValue.
- Scope drafts to the tab: sessionStorage for unsent form state and wizard steps - closing the tab is the cleanup you did not have to write.
Frequently asked questions
Why does my localStorage value come back as a string like "[object Object]"?
Because setItem stringifies its argument with the default String() conversion: storing an object directly produces the useless text '[object Object]'. The storage API's contract is strings only, so the object roundtrip is explicit: JSON.stringify before setItem, JSON.parse after getItem. The related trap: getItem returns null for MISSING keys but the string 'null' for a stored null - and JSON.parse(null) returns null by coercion luck, while JSON.parse(undefined) throws. Guard with an explicit null check before parsing anything from storage.
How does the storage event enable cross-tab synchronization?
When one tab writes to localStorage, every OTHER tab on the same origin receives a storage event carrying key, oldValue, newValue and url - the writing tab itself does NOT receive it. That asymmetry is the feature: a settings tab changes the theme, every open tab hears the event and re-renders without polling or a server. Two caveats: the event fires only when the value actually CHANGES (writing the same value is silent), and it does not fire for sessionStorage, which is deliberately tab-private.
When is sessionStorage the right choice over localStorage?
When the state's lifetime IS the tab. Draft form content the user has not sent, multi-step wizard progress, a per-tab filter or scroll position, A/B variant assignment that must stay consistent within one visit but may differ across visits - all of these want to vanish when the tab closes, and sessionStorage makes closing the tab the cleanup. localStorage would leak that state into the next session (stale drafts resurfacing days later). Both share the same API surface, so switching between them is a one-word change.
What actually separates localStorage from cookies and IndexedDB?
Direction and capacity. Cookies are small (4KB), expire on schedule, and ride EVERY HTTP request to the server - which is exactly what sessions need and exactly the overhead static data should not pay. localStorage is ~5MB, never expires, and never leaves the browser - perfect for preferences, wrong for anything the server must see per-request. IndexedDB is the async, structured, hundreds-of-MB database for files and large datasets, with a cursor API instead of key-value simplicity. The ladder: preferences to storage, server state to cookies (or better, Authorization headers), bulk data to IndexedDB.