The Web Storage API: local storage and session storage

• Introduction
• How to access the storage
• Methods
  • setItem(key, value)
  • getItem(key)
  • removeItem(key)
  • key(n)
  • clear()
• Storage size limits
  • Going over quota
• Developer Tools
  • Chrome
  • Firefox
  • Safari

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
• IndexedDB
• The 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 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 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 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 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:

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

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

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:

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:

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

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

Parse a stored JSON value like this:

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

removeItem(key)

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

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.

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:

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.

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:

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

Firefox

Safari

Related posts about platform: