Start · Sprachen · JavaScript · Referenz · Document.cookie

Document.cookie

Eigenschaft

Liest alle für das Dokument sichtbaren Cookies als String oder setzt bzw. löscht ein einzelnes Cookie per Zuweisung.

seit JavaScript Baseline: alle Browser Kategorie: webapi

Signatur

Document.cookie

Beschreibung

document.cookie ist eine Zugriffseigenschaft mit Getter und Setter, die sich ungewöhnlich verhält. Beim Lesen bekommst du alle Cookies, die für die aktuelle URL gelten und nicht als HttpOnly markiert sind. Sie stehen alle in einem einzigen String im Format "name1=wert1; name2=wert2". Attribute wie Expires, Path oder Domain sind dabei nicht enthalten.

Beim Schreiben ersetzt eine Zuweisung nicht alle Cookies. Sie setzt oder aktualisiert genau ein Cookie. Der zugewiesene String hat die Form name=wert, dahinter können durch Semikolon getrennte Attribute folgen, z. B. ; path=/; max-age=3600; secure; samesite=lax. Ein Cookie wird eindeutig über Name + Domain + Pfad bestimmt. Um es zu löschen, setzt du es mit denselben path- und domain-Werten erneut und gibst max-age=0 oder ein expires-Datum in der Vergangenheit an.

Typische Einsatzzwecke sind kleine Einstellungen, die der Server bei jeder Anfrage mitlesen soll, etwa Sprache, Theme oder die Zustimmung zu Cookies. Für reine Client-Daten eignen sich localStorage oder IndexedDB besser, denn Cookies werden bei jeder HTTP-Anfrage an die Domain mitgeschickt und sind auf etwa 4 KB pro Cookie begrenzt.

Die Syntax ist umständlich und fehleranfällig. Deshalb lohnen sich kleine Hilfsfunktionen zum Parsen und Setzen. In neueren Chromium-Browsern gibt es zusätzlich die asynchrone CookieStore-API.

Parameter

Name Typ Default Beschreibung
$wert (beim Schreiben) Pflicht string Ein einzelnes Cookie im Format name=wert, dahinter optional Attribute, getrennt durch ;:
  • path=/pfad: Pfad, für den das Cookie gilt. Ohne Angabe gilt der Pfad des aktuellen Dokuments.
  • domain=example.com: gilt dann auch für Subdomains. Ohne Angabe gilt nur der exakte Host.
  • max-age=sekunden: Lebensdauer in Sekunden. 0 oder negativ löscht das Cookie.
  • expires=Datum: Ablaufdatum im UTC-Format (Date.prototype.toUTCString()). Ohne max-age/expires entsteht ein Sitzungs-Cookie.
  • secure: Cookie wird nur über HTTPS übertragen.
  • samesite=lax|strict|none: Regelt, ob das Cookie bei seitenübergreifenden Anfragen mitgeschickt wird. none erfordert secure.
  • partitioned: CHIPS, ein partitioniertes Cookie für eingebettete Drittanbieter-Kontexte.

Rückgabewert

Typ
string
Beschreibung
Beim Lesen: alle für das Dokument zugänglichen Cookies als "name=wert; name2=wert2", ohne Attribute. Gibt es keine Cookies, ist es ein leerer String. Nach einer Zuweisung ist der Rückgabewert der zugewiesene String.

Beispiele

Cookie setzen und alle Cookies lesen

// Theme-Einstellung für 30 Tage speichern
const dreissigTage = 60 * 60 * 24 * 30;
document.cookie = `theme=dark; path=/; max-age=${dreissigTage}; samesite=lax; secure`;
document.cookie = 'lang=de; path=/; samesite=lax';

console.log(document.cookie);
theme=dark; lang=de

Hilfsfunktionen: Cookie lesen, setzen, löschen

const getCookie = (name) => {
  const eintrag = document.cookie
    .split('; ')
    .find((teil) => teil.startsWith(`${encodeURIComponent(name)}=`));
  return eintrag ? decodeURIComponent(eintrag.split('=').slice(1).join('=')) : null;
};

const setCookie = (name, wert, { maxAge, path = '/', sameSite = 'lax' } = {}) => {
  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(wert)}; path=${path}; samesite=${sameSite}`;
  if (maxAge !== undefined) cookie += `; max-age=${maxAge}`;
  if (location.protocol === 'https:') cookie += '; secure';
  document.cookie = cookie;
};

const deleteCookie = (name, path = '/') => {
  // Gleicher Pfad wie beim Setzen – sonst wird nichts gelöscht
  document.cookie = `${encodeURIComponent(name)}=; path=${path}; max-age=0`;
};

setCookie('warenkorb', 'Artikel 42; Größe M', { maxAge: 3600 });
console.log(getCookie('warenkorb'));
deleteCookie('warenkorb');
console.log(getCookie('warenkorb'));
Artikel 42; Größe M null

Cookies in ein Objekt umwandeln

const parseCookies = () =>
  Object.fromEntries(
    document.cookie
      .split(';')
      .map((teil) => teil.trim())
      .filter(Boolean)
      .map((teil) => {
        const index = teil.indexOf('=');
        return [
          decodeURIComponent(teil.slice(0, index)),
          decodeURIComponent(teil.slice(index + 1))
        ];
      })
  );

document.cookie = 'consent=true; path=/';
const cookies = parseCookies();
if (cookies.consent === 'true') {
  console.log('Nutzer hat zugestimmt – Analytics wird geladen');
}
Nutzer hat zugestimmt – Analytics wird geladen

// Wichtig · Fallstricke

  • Eine Zuweisung setzt genau ein Cookie. Mit document.cookie = 'a=1; b=2' wird nur a gesetzt. b=2 wird als (ungültiges) Attribut gelesen und ignoriert.
  • Werte kodieren: Semikolon, Komma, Leerzeichen und Nicht-ASCII-Zeichen musst du mit encodeURIComponent() kodieren. Sonst wird das Cookie abgeschnitten oder falsch geparst.
  • Löschen klappt nur mit passendem path/domain. Weichen diese ab, entsteht ein zweites Cookie mit demselben Namen, das alte bleibt bestehen. Du kannst die Attribute beim Lesen auch nicht herausfinden.
  • HttpOnly: Cookies, die der Server mit HttpOnly gesetzt hat, sind über document.cookie weder lesbar noch überschreibbar. Genau das ist der Zweck: Session-Cookies gehören immer HttpOnly vom Server gesetzt.
  • Sicherheit / XSS: Jedes Skript auf der Seite, auch eingeschleustes oder von Drittanbietern, kann alle Cookies ohne HttpOnly lesen. Speichere deshalb keine Tokens oder sensiblen Daten in per JavaScript lesbaren Cookies. Nutze secure und samesite (Schutz gegen CSRF) und setze eine Content Security Policy.
  • Grenzen: Pro Cookie gelten etwa 4096 Bytes (Name + Wert), pro Domain meist rund 50 Cookies oder mehr, je nach Browser. Alle Cookies werden bei jeder Anfrage mitgeschickt und belasten so die Performance.
  • Kontexte ohne Cookies: Für Dokumente mit file:- oder data:-URL und in Sandbox-iframes ohne allow-same-origin ist die Eigenschaft wirkungslos oder löst einen SecurityError aus. Drittanbieter-Cookies in iframes werden von vielen Browsern blockiert (Safari, Firefox; Chrome schränkt sie ebenfalls ein).
  • Lebensdauer: Safari (ITP) begrenzt per JavaScript gesetzte Cookies unter Umständen auf 7 Tage, unabhängig von max-age.
  • Kompatibilität: document.cookie funktioniert in allen Browsern. In Web Workern gibt es die Eigenschaft nicht. Die asynchrone Alternative cookieStore steht nur in Chromium-Browsern und neueren Safari-/Firefox-Versionen zur Verfügung und nur in sicheren Kontexten (HTTPS).