localStorage is a key/value storage option for client-side persistence in web applications. It provides a straightforward API and is supported by all modern browsers.
Use localStorage only for storing small amounts of simple data. For larger datasets, offline-first applications, or structured queries, IndexedDB is usually the better choice.
localStorage ¶
setItem stores a value with a certain key. The first argument is the name of the key, and the second argument is the value. Each key can only exist once. Calling setItem multiple times with the same key overwrites the previous entry. Keys and values are strings; setItem automatically converts a non-string value to a string. This is a problem for objects because they get converted to the string "[object Object]". To solve that, an application has to convert objects to a string before it calls setItem. One way to do that is with JSON.stringify().
localStorage.setItem('one', '1');
localStorage.setItem('two', 2); // automatically converts 2 to the string "2"
const myObj = {firstName: 'John', lastName: 'Doe', age: 36};
localStorage.setItem('123', JSON.stringify(myObj));
getItem retrieves the value for a specific key. The function returns null when the key does not exist.
const a = localStorage.getItem('one'); // "1"
const b = localStorage.getItem('two'); // "2"
const obj = JSON.parse(localStorage.getItem('123')); // {firstName: 'John', lastName: 'Doe', age: 36}
Another way to set and get values is by directly accessing the key like a property on the localStorage object.
localStorage.one = '1'; // same as localStorage.setItem('one', '1');
const c = localStorage.one; // same as const c = localStorage.getItem('one');
It is possible to mix both approaches.
localStorage.two = '2'
const t = localStorage.getItem('two'); // "2"
There is one subtle difference in the behavior when the key does not exist. getItem returns null, while property access returns undefined.
const x = localStorage.getItem('xyz'); // null
const y = localStorage.xyz; // undefined
When the key is not a valid name for a property, the application needs to use the ['property'] syntax, or just stick to setItem and getItem.
localStorage['11'] = 'eleven';
const e = localStorage['11']; // "eleven"
removeItem removes the entry for a specific key.
localStorage.removeItem('one');
clear removes all key/value pairs.
localStorage.clear();
Another related storage option is sessionStorage. It provides the same functions as localStorage. The key difference is that data stored in localStorage persists across browser restarts, whereas data in sessionStorage does not. However, even though data in localStorage persists, an application should not rely on it being stored indefinitely. The data can be erased at any time by the user or the browser.
In modern applications, it is usually best to prefer getItem() and setItem() over property-style access. The method-based API is clearer, avoids edge cases with property names, and matches the platform documentation.
When you need to store non-string values, convert them with JSON.stringify() before writing and JSON.parse() after reading.
localStorage.setItem('anObject', JSON.stringify({firstName: 'John', lastName: 'Doe', age: 36}));
const anObject = JSON.parse(localStorage.getItem('anObject')); // {firstName: 'John', lastName: 'Doe', age: 36}
JSON.parse() also makes it easy to provide a fallback when the key does not exist.
const settings = JSON.parse(localStorage.getItem('settings') ?? '{"theme":"light"}');