# The Web Storage API: local storage and session storage

> Learn how the Web Storage API lets you store data in the browser with local storage and session storage, using methods like setItem, getItem, and removeItem.

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2018-03-29 | Updated: 2026-07-18 | Topics: [Web Platform](https://flaviocopes.com/tags/platform/) | Canonical: https://flaviocopes.com/web-storage-api/

<!-- TOC -->

- [Introduction](#introduction)
- [How to access the storage](#how-to-access-the-storage)
- [Methods](#methods)
  - [`setItem(key, value)`](#setitemkey-value)
  - [`getItem(key)`](#getitemkey)
  - [removeItem(key)](#removeitemkey)
  - [key(n)](#keyn)
  - [clear()](#clear)
- [Storage size limits](#storage-size-limits)
  - [Going over quota](#going-over-quota)
- [Developer Tools](#developer-tools)
  - [Chrome](#chrome)
  - [Firefox](#firefox)
  - [Safari](#safari)

<!-- /TOC -->

## Introduction

The **Web Storage API** stores string key/value pairs in the browser.

It provides two storage mechanisms:

- `localStorage` persists across browser sessions
- `sessionStorage` lasts for one tab's page session

They are part of the storage options available on the Web Platform, which also include:

- [Cookies](https://flaviocopes.com/cookies/)
- [IndexedDB](https://flaviocopes.com/indexeddb/)
- [The Cache API](https://flaviocopes.com/cache-api/)

Both storage areas are separated by **origin**. The scheme, host, and port must all match. Other origins cannot read the data through Web Storage.

`sessionStorage` maintains data for the duration of the page session. Different tabs have separate page sessions, even when they show the same site.

When the tab closes, its `sessionStorage` data is cleared.

This is useful for separate workflows in different tabs. The [MDN Web Storage guide](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API#concepts_and_usage) describes how storage is partitioned.

`localStorage` is shared by same-origin pages and persists after the browser closes. The app, the user, or the browser can still clear it. Private browsing data is normally removed when the private session ends.

Web Storage is synchronous. Large reads and writes block JavaScript on the page, so use [IndexedDB](https://flaviocopes.com/indexeddb/) for larger or structured data.

Web Storage is only accessible in the browser. It's not sent to the server like cookies do.

Do not store passwords, session IDs, or authentication tokens in Web Storage. Any JavaScript running on the origin can read them, including code injected through an XSS vulnerability. The [MDN session-management guide](https://developer.mozilla.org/en-US/docs/Web/Security/Authentication/Session_management#protecting_session_data_from_xss) recommends keeping session identifiers out of JavaScript-accessible storage.

## How to access the storage

Both Local and Session Storage are available on the `window` object, so you can access them using `sessionStorage` and `localStorage`.

Their set of properties and methods is exactly the same, because they return the same object, a [Storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage) object.

The Storage object has a single property, `length`, which is the number of stored items.

## Methods

### setItem(key, value)

`setItem()` adds an item to the storage. Accepts a string as key, and a string as a value:

```js
localStorage.setItem('username', 'flaviocopes')
localStorage.setItem('id', '123')
```

If you pass any value that's not a string, it will be converted to string:

```js
localStorage.setItem('test', 123) //stored as the '123' string
localStorage.setItem('test', { test: 1 }) //stored as "[object Object]"
```

Use JSON when you want to store an object:

```js
const settings = { theme: 'dark' }
localStorage.setItem('settings', JSON.stringify(settings))
```

### getItem(key)

`getItem()` is the way to retrieve a string value from the storage, by using the key string that was used to store it:

```js
localStorage.getItem('username') // 'flaviocopes'
localStorage.getItem('id') // '123'
```

`getItem()` returns `null` when the key does not exist.

Parse a stored JSON value like this:

```js
const settings = JSON.parse(localStorage.getItem('settings'))
```

### removeItem(key)

`removeItem()` removes the item identified by `key` from the storage, returning nothing (an `undefined` value):

```js
localStorage.removeItem('id')
```

### key(n)

`key(n)` returns the name of the key at index `n`.

The order is defined by the browser, so do not rely on a particular order. See the [`Storage.key()` reference](https://developer.mozilla.org/en-US/docs/Web/API/Storage/key).

If you reference a number that does not point to a storage item, it returns `null`.

### clear()

`clear()` removes everything from the storage object you are manipulating:

```js
localStorage.setItem('a', 'a')
localStorage.setItem('b', 'b')
localStorage.length //2
localStorage.clear()
localStorage.length //0
```

## Storage size limits

Web Storage is limited to about 10 MiB per origin: 5 MiB for `localStorage` and 5 MiB for `sessionStorage`. Browsers throw `QuotaExceededError` when an origin reaches the limit. See MDN's current [storage quota guide](https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria#web_storage).

Do not treat stored data as permanent. Users can clear it, private sessions delete it, and browser storage policies can affect it.

### Going over quota

Handle quota errors, especially if you store a lot of data:

```js
try {
  localStorage.setItem('key', 'value')
} catch (error) {
  if (error.name === 'QuotaExceededError') {
    console.error('Storage quota exceeded')
  } else {
    throw error
  }
}
```

## Developer Tools

The DevTools of the major browsers all offer a nice interface to inspect and manipulate the data stored in the Local and Session Storage.

### Chrome

![Chrome DevTools local storage](https://flaviocopes.com/images/web-storage-api/localstorage-devtools-chrome.png)

### Firefox

![Firefox DevTools local storage](https://flaviocopes.com/images/web-storage-api/localstorage-devtools-firefox.png)

### Safari

![Safari DevTools local storage](https://flaviocopes.com/images/web-storage-api/localstorage-devtools-safari.png)