JavaScript localStorage Explained for Beginners (With Simple Examples)

If you’ve ever refreshed a webpage and noticed that your data disappeared, you’ve probably wondered:

“How do websites remember things?”

JavaScript has a simple but powerful feature that helps with this; localStorage.

In this article, I’ll explain localStorage from scratch, in a way that anyone can understand, even if you’re new to JavaScript.

By the end, you’ll know:

• What localStorage is

• How setItem, getItem, and clear work

• Why JSON.stringify() and JSON.parse() are important

• How to safely store arrays and objects in the browser

What is localStorage?

localStorage is a storage space provided by the browser.

Think of it as:

A small notebook that your browser keeps for a website.

Anything written in this notebook:

• Stays after refreshing the page

• Stays after closing and reopening the browser

• Is available only to that website

This makes localStorage perfect for saving small pieces of data like user preferences, form inputs, or app state.

How localStorage Stores Data

localStorage works using key–value pairs.

If you don’t know what that means, here’s a simple way to think about it:

• Key → the label

• Value → the data attached to the label

Example:

Key: "username"
Value: "Emmanuel"

Later, we can ask the browser:

“Give me the value stored under the key username.”

---

Saving Data with localStorage.setItem()

To save data, we use setItem().

Syntax

localStorage.setItem(key, value);

Example

localStorage.setItem("name", "Emmanuel");

What’s happening here?

• "name" is the key

• "Emmanuel" is the value

• The browser stores it permanently

Refresh the page; the data is still there.

---

Getting Data with localStorage.getItem()

To read data from localStorage, we use getItem().

Example

const name = localStorage.getItem("name");
console.log(name);

Output

Emmanuel

If the key does not exist, JavaScript returns:

null

---

Important Rule: localStorage Only Stores Strings

This is very important.

Even if you save a number:

localStorage.setItem("age", 25);

It is actually stored as

"25"

Everything in localStorage is saved as text (strings).

This causes issues when working with arrays and objects.

---

The Problem with Saving Arrays Directly

Let’s try saving an array:

const fruits = ["apple", "banana", "orange"];
localStorage.setItem("fruits", fruits);

What gets stored?

apple,banana,orange

That’s no longer a real JavaScript array.

To fix this, we use JSON.

---

What is JSON? (Simple Explanation)

JSON is a way to convert JavaScript data into text and back again.

You can think of it as:

A translator between JavaScript and localStorage.

---

Saving Arrays Using JSON.stringify()

To save an array properly, we convert it to a string first.

const fruits = ["apple", "banana", "orange"];

localStorage.setItem("fruits", JSON.stringify(fruits));

Now the browser stores:

["apple","banana","orange"]

This preserves the array structure.

---

Getting Arrays Back with JSON.parse()

When retrieving the data, we convert it back into JavaScript.

const storedFruits = JSON.parse(localStorage.getItem("fruits"));
console.log(storedFruits);

Output:

["apple", "banana", "orange"]

Now it behaves like a real array again:

storedFruits.push("mango");

---

Saving Objects in localStorage

Objects work the same way.

Example

const user = {
  name: "Emmanuel",
  age: 25,
  isLoggedIn: true
};

localStorage.setItem("user", JSON.stringify(user));

Retrieving the object

const storedUser = JSON.parse(localStorage.getItem("user"));
console.log(storedUser.name);

---

Clearing Data from localStorage

Remove everything

localStorage.clear();

⚠️ This deletes all localStorage data for that website.

---

Removing a Single Item

If you only want to delete one item:

localStorage.removeItem("user");

---

Common Beginner Mistakes

❌ Forgetting to parse JSON

const data = localStorage.getItem("fruits");
data.push("mango"); // Error

✅ Correct way

const data = JSON.parse(localStorage.getItem("fruits"));
data.push("mango");

---

When Should You Use localStorage?

Good use cases:

• Saving theme preferences (dark/light mode)

• Keeping users logged in

• Storing todos or cart items

Do not store:

• Passwords

• Sensitive personal data

---

Final Thoughts

localStorage is one of the easiest ways to add persistence to your JavaScript applications.

Once you understand:

• key–value pairs

• strings vs objects

• JSON.stringify() and JSON.parse()

You unlock a lot of real-world use cases.