Symbol.toPrimitive

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2015.

Symbol.toPrimitive は静的データプロパティで、ウェルノウンシンボルである Symbol.toPrimitive を表します。すべての型変換アルゴリズムにおいて、すべての型変換アルゴリズムにおいて、オブジェクト上でこのシンボルを使って、その valueOf()toString() メソッドを使用する前に、望ましい型を受け入れ、オブジェクトのプリミティブ表現を返すメソッドを調べます。

試してみましょう

const object1 = {
  [Symbol.toPrimitive](hint) {
    if (hint === "number") {
      return 42;
    }
    return null;
  },
};

console.log(+object1);
// Expected output: 42

ウェルノウンシンボル Symbol.toPrimitive です。

Symbol.toPrimitive のプロパティ属性
書込可能不可
列挙可能不可
設定可能不可

解説

Symbol.toPrimitive プロパティにより(関数値として使用することで)、オブジェクトをプリミティブ値に変換することができるようになります。関数は、プリミティブ値の結果として好ましい型を指定する文字列引数の hint と一緒に呼び出されます。hint 引数は、 "number", "string", "default" のいずれかになります。

"number" ヒントは、数値変換アルゴリズムで使用されます。"string" ヒントは、文字列変換アルゴリズムで使用されます。"default" ヒントは、プリミティブ変換アルゴリズムで使用されます。ヒントは、優先順位の弱いシグナルとしてのみ機能し、実装でそれを無視するのは自由です(Symbol.prototype[Symbol.toPrimitive]() がそうであるように)。[Symbol.toPrimitive]() はプリミティブを返さなければなりません。そうでない場合は TypeError が発生します。

[Symbol.toPrimitive] プロパティを持たないオブジェクトは、valueOf() メソッドと toString() メソッドを異なる順序で呼び出すことでプリミティブに変換されますが、これについては型変換の節で詳しく説明します。[Symbol.toPrimitive]() では、プリミティブ変換処理を完全に制御できます。例えば、Date.prototype[Symbol.toPrimitive]() は、"default""string" であるかのように扱い、 valueOf() の代わりに toString() を呼び出します。Symbol.prototype[Symbol.toPrimitive]() はヒントを無視し、常にシンボルを返します。つまり、文字列コンテキストでも Symbol.prototype.toString() は呼び出されず、Symbol オブジェクトは常に String() を介して明示的に文字列に変換する必要があります。

オブジェクトから変換されたプリミティブ値の修正

次の例は Symbol.toPrimitive プロパティがオブジェクトから変換されたプリミティブ値を修正する方法を説明します。

js
// Symbol.toPrimitive プロパティを持たないオブジェクト。
const obj1 = {};
console.log(+obj1); // NaN
console.log(`${obj1}`); // "[object Object]"
console.log(obj1 + ""); // "[object Object]"

// Symbol.toPrimitive プロパティを持つオブジェクト。
const obj2 = {
  [Symbol.toPrimitive](hint) {
    if (hint === "number") {
      return 10;
    }
    if (hint === "string") {
      return "hello";
    }
    return true;
  },
};
console.log(+obj2); // 10        — hint は "number"
console.log(`${obj2}`); // "hello"   — hint は "string"
console.log(obj2 + ""); // "true"    — hint は "default"

仕様書

Specification
ECMAScript® 2025 Language Specification
# sec-symbol.toprimitive

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
toPrimitive

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

関連情報