Storage.length — Eigenschaft · JavaScript-Referenz

Signatur

get Storage.prototype.length

Beschreibung

Die schreibgeschützte Eigenschaft length der Storage-Schnittstelle liefert als ganze Zahl, wie viele Einträge im jeweiligen Speicherobjekt liegen. Sie ist für window.localStorage und window.sessionStorage verfügbar und bezieht sich immer nur auf den Speicher des aktuellen Ursprungs (Origin), also auf die Kombination aus Protokoll, Host und Port.

Meist wird length zusammen mit Storage.key(index) verwendet, um in einer klassischen for-Schleife über alle gespeicherten Schlüssel zu laufen. Das ist z. B. nützlich, wenn man Einträge mit einem bestimmten Präfix finden, Debug-Ausgaben erzeugen oder alte Cache-Einträge aufräumen möchte. Außerdem lässt sich mit length === 0 schnell prüfen, ob der Speicher leer ist.

Der Wert ist live: Er ändert sich sofort nach setItem() mit einem neuen Schlüssel, nach removeItem() oder clear(). Wird ein bestehender Schlüssel mit setItem() überschrieben, bleibt length unverändert. Eine Zuweisung an length wird ignoriert (im Strict Mode ohne Fehler, da es sich um einen reinen Getter auf dem Prototyp handelt – die Zuweisung legt im Storage-Objekt aber ggf. einen Eintrag mit dem Schlüssel "length" an).

Beispiele

Anzahl der Einträge ermitteln

localStorage.clear();
localStorage.setItem('theme', 'dark');
localStorage.setItem('lang', 'de');
console.log(localStorage.length);

// Überschreiben ändert die Anzahl nicht
localStorage.setItem('theme', 'light');
console.log(localStorage.length);

localStorage.removeItem('lang');
console.log(localStorage.length);

2 2 1

Alle Einträge mit length und key() auflisten

const dumpStorage = (storage) => {
  const entries = {};
  for (let i = 0; i < storage.length; i++) {
    const key = storage.key(i);
    entries[key] = storage.getItem(key);
  }
  return entries;
};

sessionStorage.setItem('step', '3');
sessionStorage.setItem('cartId', 'A42');
console.log(dumpStorage(sessionStorage));

{ step: '3', cartId: 'A42' } // Reihenfolge nicht garantiert

Einträge mit Präfix sicher löschen

const removeByPrefix = (prefix) => {
  // Erst Schlüssel sammeln, dann löschen – sonst verschieben sich die Indizes
  const keys = [];
  for (let i = 0; i < localStorage.length; i++) {
    const key = localStorage.key(i);
    if (key.startsWith(prefix)) keys.push(key);
  }
  keys.forEach((key) => localStorage.removeItem(key));
  return keys.length;
};

localStorage.setItem('cache:user', '{}');
localStorage.setItem('cache:posts', '[]');
localStorage.setItem('token', 'xyz');
console.log(removeByPrefix('cache:'), localStorage.length);

2 1 // sofern vorher nur diese drei Einträge existierten

Prüfen, ob der Speicher leer ist

const isStorageEmpty = (storage = localStorage) => storage.length === 0;

if (isStorageEmpty()) {
  console.log('Erster Besuch – Standardwerte setzen');
  localStorage.setItem('theme', 'system');
}

Erster Besuch – Standardwerte setzen // beim ersten Aufruf

// Wichtig · Fallstricke

Löschen während der Iteration: Wer in einer Schleife über 0 … length - 1 mit removeItem() löscht, überspringt Einträge, weil sich length und die Indizes von key() sofort ändern. Erst Schlüssel sammeln, dann löschen – oder rückwärts iterieren.
Keine Byte-Größe: length zählt Einträge, nicht den belegten Speicher. Die Quote (typisch ca. 5 MiB pro Origin) lässt sich damit nicht prüfen; dafür eignet sich näherungsweise die Summe der Zeichenlängen oder navigator.storage.estimate().
Reihenfolge: Die Reihenfolge der Schlüssel über key(i) ist nicht spezifiziert und kann je nach Browser abweichen.
Schlüssel „length“: Mit localStorage.setItem('length', 'x') kann ein Eintrag namens length existieren; localStorage.length liefert trotzdem die Anzahl, da der Getter Vorrang hat. Zugriff auf den Eintrag daher nur über getItem('length').
Verfügbarkeit: In allen modernen Browsern unterstützt. In privaten Modi, bei deaktivierten Cookies oder in Sandbox-iframes kann schon der Zugriff auf localStorage eine SecurityError-Ausnahme werfen – Zugriff ggf. in try…catch kapseln. In Node.js existiert localStorage erst ab Version 22 (experimentell).
Änderungen durch andere Tabs spiegeln sich sofort in length wider; das storage-Event informiert darüber.

Siehe auch

Storage Storage.key() Storage.getItem() Storage.setItem() Storage.removeItem() Storage.clear() Window.localStorage Window.sessionStorage