localStorage & sessionStorage

Two places to save text in the browser

The browser can save small pieces of text for a website, so they are still there later. This is called Web Storage. It comes in two parts:

• localStorage keeps text for a long time. It is still there after you reload the page, close the browser, and come back next week. It goes away only when your code or the user deletes it.
• sessionStorage keeps text for one browser tab. A reload keeps it. Closing the tab deletes it.

Both save text in pairs. The key is a name, like theme. The value is the text saved under that name, like dark.

Each website gets its own storage. More exactly, each origin does. An origin is the start of a web address. It has three parts:

• the scheme, like https;
• the host, like example.com;
• the port, a number that is often hidden, like 443.

https://example.com and http://example.com are two different origins. They can't read each other's storage.

const theme = localStorage.getItem("theme") ?? "light";
localStorage.setItem("theme", "dark");
console.log(theme);
console.log(localStorage.getItem("theme"));

Line 1 reads the saved theme with getItem. Nothing is saved yet, so getItem gives null, which means "nothing here". The ?? operator then picks a fallback: a backup value, here "light".

Line 2 saves "dark" with setItem. Line 3 prints light. Line 4 reads the theme again and prints dark. On a real site, the next visit would start with dark.

sessionStorage.setItem("step", 2);
console.log(sessionStorage.getItem("step"));
console.log(typeof sessionStorage.getItem("step"));

Line 1 saves the number 2 in this tab's sessionStorage. Line 2 prints 2. Line 3 prints string: the number came back as text. The next section explains why.

Here is what happens to this tab's sessionStorage:

• Reload the tab: the value stays.
• Close the tab: the value is deleted.
• Open the same page in a new tab: the new tab starts empty.
• Duplicate the tab: in most browsers, the new tab starts with a copy. After that, the two copies change separately.

Use Web Storage for small things that only the browser needs, such as:

• a setting, like the theme;
• which tab or panel was open;
• whether the user has already seen a feature tour;
• a short draft of a form.

Don't use it as a database, as a safe place for secrets, or as a way to send data to the server. The section on limits explains why.

localStorage and sessionStorage have the same methods. A method is a function you call on an object, after a dot:

• setItem(key, value) saves a value under a key.
• getItem(key) reads the value saved under a key.
• removeItem(key) deletes one key and its value.
• length tells you how many keys are saved. It is a number, not a method, so it has no brackets.
• key(index) gives the name of the key at a position: 0, 1, 2, and so on.
• clear() deletes every key for this origin. Use it with care: it also deletes keys that other parts of the site saved.

1const storage = localStorage;2 3storage.setItem("count", 7);4storage.setItem("darkMode", false);5storage.setItem("profile", { name: "Ada" });6 7console.log(storage.getItem("count"));8console.log(storage.getItem("darkMode"));9console.log(storage.getItem("profile"));10console.log(storage.getItem("missing"));

One rule matters most: storage keeps only strings. A string is text. Before saving, the browser turns every value into text with String(value):

• The number 7 becomes "7".
• The boolean false becomes "false".
• An object like { name: "Ada" } becomes "[object Object]". The data inside is lost.

If a key was never saved, getItem gives null. That is why you often see a fallback after ??, like localStorage.getItem("tab") ?? "overview".

localStorage.setItem("count", 5);
const savedCount = localStorage.getItem("count");
console.log(savedCount);
console.log(typeof savedCount);

Line 1 saves the number 5. Storage turns it into the text "5". Line 3 prints 5, and line 4 prints string. Before you do math with it, turn it back into a number with Number(savedCount).

localStorage.setItem("notice", "saved");
console.log(localStorage.getItem("notice"));
localStorage.removeItem("notice");
console.log(localStorage.getItem("notice"));

Line 2 prints saved. Line 3 deletes the key. Line 4 reads the same key again and prints null. It is not an empty string, and it is not undefined.

localStorage.setItem("app:theme", "dark");
localStorage.setItem("app:draft", "Tea");
localStorage.setItem("other:setting", "keep");
localStorage.removeItem("app:theme");
console.log(localStorage.length);
localStorage.clear();
console.log(localStorage.length);

Here is what each line does:

• Lines 1 to 3 save three keys. Two start with app:. One starts with other:.
• Line 4 deletes only app:theme. Line 5 prints 2.
• Line 6 calls clear(). It deletes app:draft, and it also deletes other:setting, which belonged to another part of the site.
• Line 7 prints 0.

So give your keys a shared start, called a prefix, like app:. Then delete only the keys that start with it.

localStorage.setItem("theme", "dark");
localStorage.setItem("draft", "Tea");
for (let index = 0; index < localStorage.length; index += 1) {
  console.log(localStorage.key(index));
}

The loop starts at position 0. Before each turn, it checks index < localStorage.length. On each turn, key(index) gives one key name. This prints theme, then draft.

Here the keys come out in the order they were saved. Browsers don't promise that order, so don't write code that depends on it.

To save an object, first turn it into text. JSON is a text format for data. Two tools do the work:

• JSON.stringify(value) turns an object into JSON text.
• JSON.parse(text) turns JSON text back into an object.

Saved text can go wrong. It can be:

• missing, because nothing was saved yet;
• old, saved by an older version of your app;
• broken, for example after someone changed it by hand in the browser's developer tools.

JSON.parse throws an error when the text is broken. So read saved JSON inside try/catch. The try block runs the code. If it throws, the catch block runs instead, and the page doesn't crash.

function readJSON(key, fallback) {
  const text = localStorage.getItem(key);
  if (text === null) return fallback;
  try {
    return JSON.parse(text);
  } catch {
    return fallback;
  }
}

console.log(readJSON("missing", { theme: "light" }).theme);
localStorage.setItem("settings", "{broken json");
console.log(readJSON("settings", { theme: "light" }).theme);

Here is what happens:

• Line 11 reads the key "missing". getItem gives null, so line 3 returns the fallback right away. It prints light.
• Line 12 saves broken text under the key "settings".
• Line 13 reads it. JSON.parse on line 5 throws, so the catch on lines 6 and 7 returns the fallback. It prints light again, and the page keeps working.

1function readJSON(key, fallback) {2  const text = localStorage.getItem(key);3  if (text === null) return fallback;4  try {5    return JSON.parse(text);6  } catch {7    return fallback;8  }9}10 11const oldSettings = {12  version: 1,13  data: { theme: "dark", compact: true }14};15localStorage.setItem("cf-demo:settings", JSON.stringify(oldSettings));16 17const loaded = readJSON("cf-demo:settings", { version: 2, data: {} });18const current = loaded.version === 119  ? { version: 2, data: { ...loaded.data, textSize: "normal" } }20  : loaded;21 22localStorage.setItem("cf-demo:settings", JSON.stringify(current));

const draft = { title: "Tea", body: "Buy leaves" };
localStorage.setItem("draft", JSON.stringify(draft));
const restored = JSON.parse(localStorage.getItem("draft"));
console.log(restored.title);

Line 1 makes a small draft object. Line 2 turns it into JSON text and saves it. Line 3 reads the text and turns it back into an object. Line 4 prints Tea.

A form could do this while the user types. In a real app, read with the safe reader above, in case the saved text is old or broken.

Once real users have saved data, a later version of your app may need it in a new shape. So save a version number with the data, like { version: 2, data: settings }. When you read version 1 data, change it into the version 2 shape first. This is called a migration. Then the rest of your app only ever sees the newest shape.

The table shows four kinds of saved value. Read each row as: what you have, what storage holds, and what to do about it.

An event is a message the browser sends when something happens. When one page changes localStorage, the browser sends a storage event to the other open pages from the same origin. These can be other tabs, or an iframe: a page shown inside another page.

A change to sessionStorage sends the event too, but only to pages that share that tab's storage, such as an iframe in the same tab.

The page that made the change does not get the event. It already knows what it changed. So use the event to hear about changes from other pages, and update your own page directly.

1window.addEventListener("storage", (event) => {2  console.log(event.key);3  console.log(event.oldValue);4  console.log(event.newValue);5  console.log(event.url);6  console.log(event.storageArea === localStorage);7});8 9localStorage.setItem("cf-demo:signal", "hello");

The event tells you what changed:

• key: the key that changed.
• oldValue and newValue: the text before and after the change.
• url: the address of the page that made the change.
• storageArea: which storage changed, localStorage or sessionStorage.

If a page calls clear(), event.key is null. This lesson's demos never call localStorage.clear(). They delete only keys that start with cf-demo:, because this website saves its own keys too, like your theme.

Many sites remember the last tab, panel, or filter you picked. The code is short. It has four steps:

1. Read the saved tab, with a fallback.
2. The visitor picks a tab.
3. Save the new tab name.
4. On the next visit, read it again.

The step-through below uses a small pretend storage, built on a Map. It has the same getItem and setItem methods. The lesson uses it because Node.js, which runs this lesson's checks, has no browser localStorage.

1const storage = makeStorage();Run2const fallback = "overview";3let activeTab = storage.getItem("lastTab") ?? fallback;4 5activeTab = "examples";6storage.setItem("lastTab", activeTab);7 8const nextVisit = storage.getItem("lastTab") ?? fallback;9console.log(nextVisit);

The page changes the tab on screen first. Then it saves the choice. Storage doesn't control every click. It only helps choose the first tab on the next visit.

Web Storage is small on purpose. Many browsers allow about 5 MB for each origin, but the real limit changes from browser to browser. A quota is the most space you are allowed.

When storage is full, setItem throws an error named QuotaExceededError. Catch that error, so the page keeps working without the saved value.

const storage = {
  setItem() {
    const error = new Error("storage is full");
    error.name = "QuotaExceededError";
    throw error;
  }
};

try {
  storage.setItem("draft", "Tea");
} catch (error) {
  console.log(error.name);
  console.log("Keep the draft in memory");
}

Lines 1 to 7 make a pretend storage. Its setItem always throws an error with the same name a full browser storage uses. Line 10 tries to save. The catch block runs instead: line 12 prints QuotaExceededError, and line 13 prints Keep the draft in memory. The draft stays in a normal variable, so the form still works.

1try {2  localStorage.setItem("cf-demo:settings", jsonText);3} catch (error) {4  // Storage is full or not available: keep going without it.5}

Each row below is a case where Web Storage is the wrong choice. Read it as: the problem, why it matters, and what to use instead.

The next lesson is about IndexedDB, a real database inside the browser. For now, use this simple rule:

• Small text that only the browser needs: Web Storage.
• A tiny value the server needs: a cookie. The browser sends cookies to the server with each request.
• Lots of data, or data with many fields: IndexedDB.

Common misconceptions

• "It stores JavaScript values." It stores only strings. Use JSON for plain objects. Rebuild special values, like a Date, yourself after reading.
• "sessionStorage is deleted when I reload." A reload keeps it. Closing the tab deletes it.
• "Every tab shares sessionStorage." Tabs from the same origin share localStorage. Each tab has its own sessionStorage.
• "The storage event tells my page about its own change." The event goes to the other pages from the same origin, not to the page that saved.
• "It is safe because users can't see it." Users can see it in the developer tools, and any script on the page can read it. Never put secrets there.
• "clear() is a harmless reset." It deletes every key in that storage for this origin. Delete only your own keys, the ones with your prefix.

Key takeaways

• localStorage keeps text for an origin for a long time. sessionStorage keeps text for one tab.
• Storage keeps only strings. getItem gives null for a missing key.
• Save objects as JSON. Read them with a fallback and try/catch, and save a version number with them.
• The storage event goes to the other pages from the same origin, not to the page that saved.
• Catch errors when storage is full, never save secrets, and use IndexedDB or cookies when they fit better.

Final definition: Web Storage lets a page save small pieces of text in the browser, as key and value pairs, for one origin. localStorage keeps them across visits, and sessionStorage keeps them for one tab. Each read and write makes the page wait until it is done.

Up next: IndexedDB.