localStorage: Your Browser's Persistent Key-Value Store

Why it exists

Web applications needed a simple way to store small amounts of data on the client-side that would persist between sessions. Before localStorage, cookies were often used for this, but they are sent with every HTTP request, adding unnecessary overhead. localStorage provides a dedicated, larger storage area that stays in the browser.

The mental model

Think of localStorage as a small filing cabinet in your browser, specific to one website (its origin). Each drawer is labeled with a key (a string), and inside you can only place a single piece of paper with a string written on it. This cabinet stays put even if you close the browser and come back later. It's separate from the filing cabinet for any other website.

How it works

The browser provides a localStorage object on the global window. You interact with it using simple methods: localStorage.setItem('key', 'value') to save data, localStorage.getItem('key') to read it, and localStorage.removeItem('key') to delete it. All keys and values are automatically converted to strings. The data is tied to the document's origin, meaning http://example.com and https://example.com have separate storage areas.

When to use it

Use it for small amounts of non-sensitive data that improve user experience by persisting across sessions. Good examples include storing a user's preferred theme (e.g., 'dark'), remembering a form's contents before submission, or noting whether a user has already seen a welcome tour.

When not to use it

Never store sensitive information like authentication tokens, passwords, or personal user data in localStorage. It is accessible via JavaScript, making it vulnerable to Cross-Site Scripting (XSS) attacks. If a malicious script runs on your page, it can read everything in localStorage. Also, it's a synchronous API, so storing or reading large amounts of data can block the main thread and make your UI unresponsive. For larger or more complex data, consider IndexedDB.

One canonical example

A common use case is saving a user's theme preference. To save the choice, you'd run localStorage.setItem('theme', 'dark');. On the user's next visit, you retrieve and apply it: const savedTheme = localStorage.getItem('theme'); if (savedTheme) { document.body.className = savedTheme; }. This simple pattern ensures the user's choice is remembered across sessions.