Die Methode Date.prototype[Symbol.toPrimitive]() steuert, wie ein Date-Objekt in einen primitiven Wert umgewandelt wird, wenn die Sprachlaufzeit eine implizite Konvertierung benötigt. Sie hat Priorität vor valueOf() und toString() und entscheidet anhand eines hint-Parameters, ob ein String oder eine Zahl zurückgegeben wird. Damit ist sie die feinste Stellschraube für das Konvertierungsverhalten und löst die historisch mehrdeutige Situation, in der Date je nach Kontext mal als String und mal als Zahl interpretiert werden musste.

01 · Abschnitt

Funktionsweise

Wenn JavaScript ein Objekt in einen primitiven Wert umwandeln muss, wird zuerst [Symbol.toPrimitive] aufgerufen – falls vorhanden. Erst wenn diese Methode nicht existiert, fällt die Sprache auf valueOf() und toString() zurück.

Der hint-Parameter teilt der Methode den gewünschten Zieltyp mit:

HintWann ausgelöstDate-Verhalten
"string"String-Kontext (z. B. Template-Literal)wie toString()
"number"Numerischer Kontext (z. B. <, -)wie valueOf()
"default"Mehrdeutig (z. B. +, ==)bei Date wie "string" (besonderheit!)

Diese Sonderbehandlung für "default" ist der Grund, weshalb date1 + date2 zwei String-Konkatenationen ergibt und nicht etwa eine Summe von Timestamps – ein historisches Erbe, das durch Symbol.toPrimitive explizit kodifiziert wurde.

02 · Abschnitt

Syntax

JavaScript Syntax 
date[Symbol.toPrimitive](hint)
Parameter
hint

Ein String aus "string", "number" oder "default". Wird von der Sprachlaufzeit automatisch passend zur Konvertierung gesetzt – manuell selten benötigt.

Rückgabewert

  • Bei hint === "string" oder hint === "default": Ein String wie von toString().
  • Bei hint === "number": Eine Zahl wie von valueOf().
  • Bei einem ungültigen hint wirft die Methode einen TypeError.
03 · Abschnitt

Beispiele

Manueller Aufruf mit verschiedenen Hints

JavaScript Beispiel 
const date = new Date("2026-05-01T14:30:00Z");

console.log(date[Symbol.toPrimitive]("string"));
console.log(date[Symbol.toPrimitive]("number"));
console.log(date[Symbol.toPrimitive]("default"));
Output 
Fri May 01 2026 16:30:00 GMT+0200 (Mitteleuropäische Sommerzeit)
1777689000000
Fri May 01 2026 16:30:00 GMT+0200 (Mitteleuropäische Sommerzeit)

Sonderverhalten: + ergibt Strings, nicht Summe

Da hint === "default" bei Date in eine String-Konvertierung fällt, ergibt date + date eine Konkatenation.

JavaScript Beispiel 
const a = new Date("2026-05-01T00:00:00Z");
const b = new Date("2026-05-02T00:00:00Z");

console.log(typeof (a + b));
console.log(typeof (a - b));
Output 
string
number

Erzwungene numerische Konvertierung mit +

Der Unary-Plus-Operator nutzt hint === "number" und liefert den Timestamp.

JavaScript Beispiel 
const date = new Date("2026-05-01T00:00:00Z");
console.log(+date);
Output 
1777593600000

Vergleich: Hint-getriebene Konvertierung

JavaScript Beispiel 
const a = new Date("2026-05-01");
const b = new Date("2026-05-02");

console.log(a < b);   // hint: "number"
console.log(`${a}`);  // hint: "string"
Output 
true
Fri May 01 2026 02:00:00 GMT+0200 (Mitteleuropäische Sommerzeit)

Ungültiger Hint führt zu TypeError

JavaScript Beispiel 
const date = new Date();
try {
    date[Symbol.toPrimitive]("xxx");
} catch (err) {
    console.log(err.name, err.message);
}
Output 
TypeError invalid hint
04 · Abschnitt

Hinweise & verwandte Methoden

  • Symbol.toPrimitive ist eine vorwärts-kompatible Erweiterung der älteren valueOf()/toString()-Mechanik. Wer [Symbol.toPrimitive] definiert, übernimmt vollständig die Kontrolle.
  • Für manuelle Konvertierungen lieber explizit aufrufen: date.getTime(), date.toISOString(), date.toLocaleString() – das ist deutlich lesbarer als +date oder String(date).
  • Eigene Klassen können [Symbol.toPrimitive] definieren, um Date-ähnliches Konvertierungsverhalten zu implementieren.
  • Bei JSON-Serialisierung wird nicht [Symbol.toPrimitive] aufgerufen, sondern toJSON().
/ Weiter

Zurück zu Date

Zur Übersicht