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.
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.
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.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
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]". UseJSON.stringify()andJSON.parse(), and wrapparseintry...catchin case the data is corrupt. getItem()returnsnull, notundefined. UsegetItem("x") ?? defaultValue.- Synchronous. Large reads and writes block the main thread, so keep values small. For big or structured data use IndexedDB.
- The
storageevent. When another tab of the same origin changes the data,windowfiresstoragewithkey,oldValueandnewValue. 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;
localStoragenever is.sessionStorageis 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.