LocalStorage Basics

What localStorage is for

localStorage is a simple key–value store built into the browser. It is useful for small preferences or draft state that should survive a page refresh, such as a theme choice or a locally saved calculator setting. Unlike a JavaScript variable, its contents remain after the page reloads. It is scoped to the browser and device being used: another device or browser does not automatically share it.

That makes it handy for your persistence quest, but it is not a database for shared progress. Clearing the site’s data in browser settings removes it, so never promise that localStorage is permanent.

Save, read and remove values

The three methods you need are setItem, getItem and removeItem. Each key is a string. getItem returns the stored string, or null if the key is absent.

localStorage.setItem('theme', 'dark');
const savedTheme = localStorage.getItem('theme');
if (savedTheme !== null) {
  console.log('Saved preference:', savedTheme);
}
localStorage.removeItem('theme');

In your quest, store a value after the user changes state, then read it as the app starts. Check for a missing value and choose a sensible default. Remove one key when you want to clear only that item; clearing all site data is a broader browser action.

Know where it lives

LocalStorage is per browser profile and device. It survives refreshes and browser restarts, but it does not travel with an account to another device. A server-backed database is the right choice when progress should follow a user between devices.

Also remember that localStorage only stores strings. For a plain text preference, that is straightforward. For arrays or objects, convert the value to JSON text when saving and turn it back into JavaScript data when reading; the companion lesson explains that conversion.

Use it deliberately

Keep stored data small and give keys clear names. Your app should still work if the key is missing, outdated or removed. Treat persistence as a convenience, not as a guarantee: browser data can be cleared, and it belongs to one browser context.

As you build, refresh the page to verify the value returns. Then remove the key and test the empty-state path. Trying both paths confirms the app does not depend on a saved value always being present.

A preference rehearsal you can inspect

On your own locally served practice page, set a harmless key in Console:

localStorage.setItem('practice:theme', 'dark');
console.log(localStorage.getItem('practice:theme'));

Refresh and read it again: it should still be dark. Open DevTools Application → Local Storage (panel names vary by browser) and locate that exact key under your page's origin. Remove only practice:theme with removeItem, refresh and expect null. Do not use clear() on the academy or another real app, because it removes unrelated settings too.

Storage belongs to an origin (scheme, hostname and port), not every page everywhere. localhost:3000 and localhost:5173 can have different storage. Two tabs at the same origin usually share the stored data, but changing storage does not automatically rerender your JavaScript UI; your code must update state or respond to relevant events. Private browsing and browser restrictions can change availability and lifetime.

For your calculator, decide when you save and when you restore. A variable disappears on reload; a saved string returns only if you read and apply it at startup. Changing the displayed total alone does not preserve the visitor's quantities. Store the harmless source quantities, not a total that can become inconsistent with them.

Before assessment, demonstrate a save, refresh, restore and missing-key default on your own app. Inspect the origin when a value seems to disappear, and handle storage failure without stopping the calculator. The following JSON lesson turns those strings into structured state safely.