The Web Storage API

The complete API

Both localStorage and sessionStorage implement the same Storage interface. Every method and property below applies to both — just swap the object name.

`setItem(key, value)`

Stores a string value under a string key. If the key already exists the value is overwritten (there is no separate “update” method).

localStorage.setItem('demo:theme', 'dark');
localStorage.setItem('demo:theme', 'light'); // overwrites — now 'light'

`getItem(key)`

Returns the stored string for the given key, or null (not undefined) if the key does not exist.

const theme = localStorage.getItem('demo:theme');  // 'light'
const missing = localStorage.getItem('demo:nope'); // null

Always guard against null before using the returned value.

`removeItem(key)`

Deletes a single key/value pair. Calling it on a key that does not exist is a no-op — no error is thrown.

localStorage.removeItem('demo:theme');
console.log(localStorage.getItem('demo:theme')); // null

`clear()`

Deletes all key/value pairs in the store for the current origin. Use with caution on localStorage — it wipes every key set by every script on the origin.

localStorage.clear();
console.log(localStorage.length); // 0

`key(index)`

Returns the key name at the given numeric index (0-based), or null if the index is out of range. The ordering is not guaranteed to be insertion order — treat it as implementation-defined.

localStorage.setItem('demo:a', '1');
localStorage.setItem('demo:b', '2');
console.log(localStorage.key(0)); // 'demo:a' or 'demo:b' — order varies

`length`

A read-only property that returns the number of key/value pairs currently stored. Use it to iterate all keys:

for (let i = 0; i < localStorage.length; i++) {
  const k = localStorage.key(i);
  console.log(k, localStorage.getItem(k));
}

Runnable: the full API in action

Browser Storage

localStorage.setItem('demo:user', 'Ada');
console.log('get:', localStorage.getItem('demo:user'));
console.log('length:', localStorage.length);
localStorage.removeItem('demo:user');
console.log('after remove:', localStorage.getItem('demo:user'));

Reading a missing key returns null

This is one of the most common bugs with Web Storage: confusing null with a stored value.

// Nothing stored yet
const val = localStorage.getItem('demo:nonexistent');
console.log(val);        // null
console.log(val === null); // true — use === null check, not falsy !val

Be careful: the string "null" is a valid stored value that is truthy. Always use === null rather than !val to distinguish “key absent” from “key present with an empty or falsy value”.

Iterating all keys

localStorage.setItem('demo:one', '1');
localStorage.setItem('demo:two', '2');

for (let i = 0; i < localStorage.length; i++) {
  const key = localStorage.key(i);
  console.log(key, '->', localStorage.getItem(key));
}

// Clean up
localStorage.removeItem('demo:one');
localStorage.removeItem('demo:two');

Trade-offs

Option	Benefit	Cost
Simple key/value API (`setItem`/`getItem`)	Fast to learn, no schema or config needed	No query, index, or transaction — you iterate manually with `key(i)`/`length` if you need to search
`clear()` wipes the whole origin	Clears everything in a single call, good for a full logout	Clears every key set by every script on that origin, not just your own — risks accidentally deleting another library’s data
Returns `null` when a key is absent	Easy to check with `=== null`, no separate `undefined` handling	A developer who uses `!value` instead of `=== null` can’t tell “no key” apart from “a stored falsy value”

Common mistakes

Checking the returned value with !value instead of === null — the string "null" or "" is falsy but is a genuinely stored value, leading to broken logic.
Calling clear() assuming it only clears your own keys — it clears every key on that origin, including ones from other libraries or scripts.
Assuming key(i) order matches insertion order — the spec doesn’t guarantee this order; never rely on the index to refer to a specific key.