Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Browser and Web APIs

The localStorage object

Reference for localStorage: setItem(), getItem(), removeItem(), clear(), storing JSON, size limits, the storage event, errors and security notes.

localStorage is a small key-value store that belongs to your site's origin (scheme, host and port). Data survives page reloads and browser restarts until your code or the user clears it. Both keys and values are strings, and every call is synchronous.

It is ideal for preferences such as a theme or a dismissed banner. It is not a database, not secure, and not shared between different origins. Any script running on your page can read it, so never store passwords, tokens that grant access or personal data in it.

JavaScript
localStorage.setItem("theme", "dark");
console.log(localStorage.getItem("theme"));

Try it

The preview sandbox has no storage of its own, so the first call throws. That is why real code wraps storage access in try...catch.

JS Real localStorage, guarded

Press Run (or Ctrl + Enter) to see the console output here.

No output.

To see the API behave, here is a tiny in-memory stand-in with the same methods, plus the JSON helper pattern you would use on real storage.

JS The same API, in memory

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
localStorage.setItem(key, value)
localStorage.getItem(key)
localStorage.removeItem(key)
localStorage.clear()
localStorage.key(index)
localStorage.length
Member Description
setItem(key, value) Stores value converted to a string. Overwrites an existing key.
getItem(key) Returns the stored string, or null if the key does not exist.
removeItem(key) Deletes the key. Nothing happens if it is missing.
clear() Deletes everything stored by this origin.
key(index) Name of the key at that position, or null.
length Number of stored pairs.

Property syntax also works (localStorage.theme = "dark"), but setItem() avoids clashes with built-in names such as length.

Exceptions: setItem() throws a QuotaExceededError when the origin's space (around 5 MB, depending on the browser) is full. Merely touching localStorage can throw a SecurityError when storage is blocked: in sandboxed frames, with strict privacy settings, or in some private modes.

Usage notes

  • Strings only. setItem("n", 5) stores "5" and objects become "[object Object]". Use JSON.stringify() and JSON.parse(), and wrap parse in try...catch in case the data is corrupt.
  • getItem() returns null, not undefined. Use getItem("x") ?? defaultValue.
  • Synchronous. Large reads and writes block the main thread, so keep values small. For big or structured data use IndexedDB.
  • The storage event. When another tab of the same origin changes the data, window fires storage with key, oldValue and newValue. It does not fire in the tab that made the change.
  • Not private. Treat it as user-editable; validate anything you read back.
  • Versioning. Prefix keys (app:v2:settings) so you can migrate or discard old formats.
  • Related stores. Cookies are sent to the server automatically; localStorage never is. sessionStorage is cleared when the tab closes.

Browser support

Supported in every browser, but availability varies with privacy settings, so always guard access and provide a fallback.