Local Storage And State

Every time a user refreshes a page, JavaScript starts fresh. Variables are gone, user preferences are lost, and any work in progress disappears. The Web Storage API — specifically localStorage and sessionStorage — solves this by giving you a simple key-value store that survives page reloads.

Beyond persistence, this lesson introduces the concept of state: the data your application depends on at any given moment. Learning to manage state explicitly, even without a framework, is one of the most important skills you can develop as a JavaScript developer.

The Web Storage API

Both localStorage and sessionStorage share the same API. The difference is lifetime:

Storage	Lifetime
`localStorage`	Persists until explicitly cleared — survives browser restarts
`sessionStorage`	Cleared when the browser tab is closed

Both are synchronous, store only strings, and have a per-origin size limit of roughly 5–10 MB.

The core methods are the same for both:

// Store a value
localStorage.setItem("username", "alice");

// Retrieve it
const name = localStorage.getItem("username");
console.log(name); // "alice"

// Remove a single key
localStorage.removeItem("username");
console.log(localStorage.getItem("username")); // null

// Clear everything
localStorage.setItem("a", "1");
localStorage.setItem("b", "2");
console.log(localStorage.length); // 2
localStorage.clear();
console.log(localStorage.length); // 0

Notice that getItem returns null — not undefined — when a key does not exist. Always check for null explicitly when reading values that might not be set yet.

Storing Objects with JSON

localStorage can only store strings. If you try to store an object directly, it gets coerced to "[object Object]", which is useless. The solution is JSON.stringify on the way in and JSON.parse on the way out.

const settings = {
  theme: "dark",
  fontSize: 16,
  notifications: true,
};

// Serialize the object to a JSON string before storing
localStorage.setItem("settings", JSON.stringify(settings));

// Parse it back when reading
const raw = localStorage.getItem("settings");
const loaded = raw ? JSON.parse(raw) : null;

console.log(loaded);            // { theme: "dark", fontSize: 16, notifications: true }
console.log(loaded.theme);      // "dark"
console.log(loaded.fontSize);   // 16 (number, not string)

// Clean up
localStorage.removeItem("settings");

JSON.parse restores the correct types too — numbers stay numbers, booleans stay booleans. The round-trip is lossless for plain objects and arrays.

Managing State as a Single Object

A common pattern is to represent your entire application state as one object, serialize it on every change, and rehydrate it on load. This keeps your persistence logic in one place and makes it easy to reason about what your app remembers.

// Define the initial shape of state
const defaultState = {
  counter: 0,
  lastUpdated: null,
  history: [],
};

// Load persisted state, falling back to defaults
function loadState() {
  const raw = localStorage.getItem("appState");
  return raw ? JSON.parse(raw) : { ...defaultState };
}

// Save state to localStorage after every change
function saveState(state) {
  localStorage.setItem("appState", JSON.stringify(state));
}

// State mutation helpers — always return a new object
function increment(state) {
  return {
    ...state,
    counter: state.counter + 1,
    lastUpdated: new Date().toISOString(),
    history: [...state.history, state.counter + 1],
  };
}

function reset(state) {
  return { ...defaultState };
}

// Boot: load state and apply a few changes
let state = loadState();
console.log("Loaded:", state.counter);

state = increment(state);
state = increment(state);
state = increment(state);
saveState(state);

console.log("Counter:", state.counter);        // 3
console.log("History:", state.history);        // [1, 2, 3]
console.log("Last updated:", state.lastUpdated);

// Simulate a reload by loading again from storage
const rehydrated = loadState();
console.log("After reload, counter:", rehydrated.counter); // 3

// Clean up
localStorage.clear();

Notice that increment never mutates the existing state object — it returns a new one using the spread operator. This pattern, called immutable state updates, makes your logic easier to test and debug because each state transition is an explicit transformation.

Reacting to Storage Changes

When two browser tabs are open on the same origin, localStorage is shared. You can listen for changes made in other tabs using the storage event on window. This is useful for syncing state across tabs — for example, logging out everywhere when the user signs out in one tab.

// This event only fires in OTHER tabs, not the one that made the change
window.addEventListener("storage", (event) => {
  console.log("Key changed:", event.key);
  console.log("Old value:", event.oldValue);
  console.log("New value:", event.newValue);
  console.log("Origin:", event.url);
});

// Simulate what another tab might do
localStorage.setItem("session", JSON.stringify({ userId: 42 }));
localStorage.removeItem("session");

// The event listener above would fire in any other open tab,
// but not in this one — that is the intended behavior.
console.log("Storage event listener registered.");
console.log("Open this page in another tab to see cross-tab sync.");

// Clean up
localStorage.clear();

The storage event is a low-cost way to keep multiple tabs in sync without polling or a WebSocket connection.

Try It Yourself

Build a small note-taking state manager. It should support adding notes, listing them, and clearing them — all persisted across reloads.

const STORAGE_KEY = "notes";

function loadNotes() {
  const raw = localStorage.getItem(STORAGE_KEY);
  return raw ? JSON.parse(raw) : [];
}

function saveNotes(notes) {
  localStorage.setItem(STORAGE_KEY, JSON.stringify(notes));
}

function addNote(notes, text) {
  const note = {
    id: Date.now(),
    text,
    createdAt: new Date().toISOString(),
  };
  return [...notes, note];
}

function deleteNote(notes, id) {
  return notes.filter((note) => note.id !== id);
}

// --- Simulate usage ---

let notes = loadNotes();
console.log("Starting notes:", notes.length);

notes = addNote(notes, "Buy groceries");
notes = addNote(notes, "Finish the lesson on localStorage");
notes = addNote(notes, "Call the dentist");
saveNotes(notes);

console.log("After adding 3 notes:", notes.length);
notes.forEach((n) => console.log(" -", n.text));

// Delete the first note
const firstId = notes[0].id;
notes = deleteNote(notes, firstId);
saveNotes(notes);

console.log("After deleting first note:", notes.length);
notes.forEach((n) => console.log(" -", n.text));

// Simulate a page reload
const reloaded = loadNotes();
console.log("After reload:", reloaded.length, "notes");

// Clean up
localStorage.clear();
console.log("Storage cleared.");

Try extending this: add a pinned boolean to each note, or write a updateNote function that replaces a note by id. Notice how keeping state as a plain array of objects makes all these operations straightforward.

Key Takeaways

localStorage persists data across browser restarts; sessionStorage is cleared when the tab closes
Both APIs only store strings — use JSON.stringify and JSON.parse to handle objects and arrays
Always provide a fallback when reading from storage — getItem returns null for missing keys
Represent application state as a single object and serialize it on every change; rehydrate it on load
Immutable state updates (spreading into a new object rather than mutating in place) make state changes predictable and debuggable
The storage event lets you react to changes made in other tabs on the same origin
localStorage is synchronous and blocks the main thread — keep stored payloads small and avoid reading/writing in tight loops

Pro Tip: Wrap all your localStorage calls in a helper module with a consistent prefix for your app's keys (e.g., "myapp:settings" instead of "settings"). This prevents collisions with third-party scripts or browser extensions that share the same origin storage, and makes it trivial to nuke just your app's data without touching anything else.