Storage.setItem() — Methode · JavaScript-Referenz

Signatur

Storage.prototype.setItem(keyName, keyValue)

Beschreibung

setItem() legt einen Eintrag im Storage-Objekt an. Wenn es den Schlüssel noch nicht gibt, wird er neu erstellt. Gibt es ihn schon, wird sein Wert überschrieben. Die Methode gehört zur Schnittstelle Storage und wird fast immer über window.localStorage (dauerhaft, pro Origin) oder window.sessionStorage (nur für die aktuelle Sitzung im Tab) aufgerufen.

Schlüssel und Werte sind immer Strings. Jeder andere Wert wird vor dem Speichern in einen String umgewandelt. Aus 42 wird "42", aus true wird "true" und aus einem Objekt wird "[object Object]". Objekte und Arrays solltest du deshalb vorher mit JSON.stringify() umwandeln und beim Auslesen mit JSON.parse() zurückholen.

Die Methode ist synchron und blockiert den Hauptthread. Das ist für kleine Mengen wie Einstellungen, Theme-Auswahl, Formularentwürfe oder Feature-Flags gedacht, nicht für große Datenmengen. Wenn ein Wert geändert wird, lösen andere Fenster und Tabs desselben Origins das Ereignis storage aus. Damit lässt sich der Zustand zwischen Tabs abgleichen.

Parameter

Name	Typ	Default	Beschreibung
$keyName Pflicht	string		Name des Schlüssels, der angelegt oder überschrieben wird. Andere Typen werden in einen String umgewandelt.
$keyValue Pflicht	string		Wert, der unter dem Schlüssel gespeichert wird. Andere Typen werden mit `String()` umgewandelt. Objekte deshalb vorher mit `JSON.stringify()` serialisieren.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Einfachen Wert speichern und auslesen

localStorage.setItem('theme', 'dark');
console.log(localStorage.getItem('theme'));

// Vorhandenen Schlüssel überschreiben
localStorage.setItem('theme', 'light');
console.log(localStorage.getItem('theme'));

dark light

Objekte per JSON speichern

const settings = { lang: 'de', fontSize: 16, notifications: true };

// Ohne JSON.stringify würde "[object Object]" gespeichert
localStorage.setItem('settings', JSON.stringify(settings));

const loaded = JSON.parse(localStorage.getItem('settings') ?? '{}');
console.log(loaded.fontSize, typeof loaded.fontSize);

16 number

Sicher speichern mit Fehlerbehandlung (Speicher voll)

const safeSetItem = (key, value) => {
  try {
    localStorage.setItem(key, JSON.stringify(value));
    return true;
  } catch (err) {
    if (err instanceof DOMException && err.name === 'QuotaExceededError') {
      console.warn('Speicher voll – Eintrag nicht gespeichert:', key);
    } else {
      console.warn('Storage nicht verfügbar:', err);
    }
    return false;
  }
};

console.log(safeSetItem('draft', { title: 'Entwurf', body: 'Text …' }));

true

Formularentwurf in sessionStorage sichern und Tabs synchronisieren

const textarea = document.querySelector('#comment');

// Entwurf bei jeder Eingabe speichern
textarea.addEventListener('input', () => {
  sessionStorage.setItem('comment-draft', textarea.value);
});

// Beim Laden wiederherstellen
textarea.value = sessionStorage.getItem('comment-draft') ?? '';

// Änderungen an localStorage aus anderen Tabs empfangen
window.addEventListener('storage', (event) => {
  if (event.key === 'theme') {
    document.documentElement.dataset.theme = event.newValue;
  }
});

// Wichtig · Fallstricke

Speicher voll: Ist das Kontingent erschöpft (meist etwa 5 MiB pro Origin), wirft setItem() eine DOMException mit dem Namen QuotaExceededError. Setze Aufrufe deshalb in try…catch.
Nicht immer verfügbar: Wenn Cookies oder Website-Daten blockiert sind, führt oft schon der Zugriff auf localStorage zu einem SecurityError. In manchen privaten Modi ist der Speicher kurzlebig oder sehr klein. Ältere Safari-Versionen haben im privaten Modus bei jedem setItem() einen Fehler geworfen.
Nur Strings: setItem('count', 1) speichert "1". setItem('x', null) speichert den String "null", löscht also nicht. Zum Löschen dient removeItem().
Das storage-Ereignis wird nur in anderen Dokumenten desselben Origins ausgelöst, nicht im Tab, der die Änderung vornimmt. Es wird auch nur ausgelöst, wenn sich der Wert tatsächlich ändert.
Sicherheit: Speichere hier keine Zugangstokens, Passwörter oder personenbezogenen Daten. Jedes Skript auf der Seite kann darauf zugreifen, auch eingeschleustes Skript bei einer XSS-Lücke. Die Daten werden außerdem unverschlüsselt auf der Festplatte abgelegt. Gespeicherte Werte beim Einfügen in den DOM nicht ungeprüft per innerHTML ausgeben.
Leistung: Die Methode arbeitet synchron. Für große oder strukturierte Datenmengen ist IndexedDB besser geeignet.
Die Eigenschaftsschreibweise localStorage.key = value funktioniert zwar auch, kann aber mit eingebauten Methoden wie key oder length kollidieren. setItem() ist die sichere Variante.

Siehe auch

Storage.getItem() Storage.removeItem() Storage.clear() Storage.key() Window.localStorage Window.sessionStorage JSON.stringify()