# Web Storage

Web Storage provides origin-scoped localStorage and sessionStorage key-value stores that browser scripts access synchronously.

- Type: term
- Domain: Engineering & architecture
- Level: Foundational
- Last reviewed: 2026-09-23
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/web-storage/>)

## What it means

Web Storage is the browser API exposing localStorage and sessionStorage as string key-value stores. localStorage persists for an origin across browser sessions subject to user controls, while sessionStorage is separated by origin and top-level browsing context and lasts for the page session. It is distinct from cookies, IndexedDB, Cache Storage, and the broader Storage API.

## Why it matters

Web Storage is simple for small preferences or transient state, but synchronous access can block the main thread and stored values are available to scripts running in the origin. Scope, lifetime, privacy, and failure behavior affect product correctness.

## When to use it

Use it for small, non-sensitive strings such as a dismissed hint or local display preference. Use IndexedDB for larger structured data, cookies only when data must accompany HTTP requests, and server storage for authoritative cross-device state.

## How it works

1. Choose localStorage or sessionStorage according to the required scope and lifetime.
2. Serialize the minimal string value and write it under a stable key.
3. Read defensively because values may be absent, stale, malformed, or unavailable.
4. Handle storage events when same-origin documents must notice localStorage changes.
5. Version and remove obsolete keys while respecting consent and reset behavior.

## A practical example

A documentation site stores a user's preferred code language in localStorage. The server still returns a usable default, the client validates the stored value, and a settings action lets the user reset it.

## Where it breaks

Operations are synchronous, capacity is limited and browser-dependent, users or browsers can clear data, and storage may be partitioned. Any script executing in the origin can potentially read values, so it is not a safe place for secrets.

## Common mistakes

- Storing access tokens or sensitive personal data because the store feels local.
- Confusing localStorage persistence with guaranteed durable storage.
- Writing large structured datasets on the main thread.
- Assuming sessionStorage is shared normally across all tabs.

## Sources

1. [Web Storage API](<https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API>) — MDN Web Docs · Official technical documentation
2. [HTML Standard: Web Storage](<https://html.spec.whatwg.org/multipage/webstorage.html>) — WHATWG · Living web standard

## Related topics

- [IndexedDB](<https://wiki.soroush.uk/topic/indexeddb/>)
- [Cookie](<https://wiki.soroush.uk/topic/cookie/>)
- [Same-Origin Policy](<https://wiki.soroush.uk/topic/same-origin-policy/>)
