JS: Symbol Tutorial

By Xah Lee. Date: 2016-11-04. Last updated: 2023-01-18.

New in JS2015.

What is Symbol

Symbol is a Primitive Value.
Symbol is one of the allowed type for a object's Property Key.
The purpose of symbol is to avoid property name collision.
Every user-created symbol value is unique and immutable.
A symbol value may have an associated value called “Description”, usually denoted in document as [[Description]]. Its value is either undefined or a string. This [[Description]] cannot be changed once created.

Create Symbol

Symbol()

Return a symbol.

// create symbol
const xx = Symbol();
console.log(xx);
// prints Symbol()

Symbol(description)

Return a symbol with description string description.

The description is a printed representation of the symbol, mostly for debugging purposes.
The description is used when you convert symbol to string.

🛑 WARNING: 2 symbols with same description are still different symbols.

// create symbol
const zz = Symbol("my cat");
console.log(zz);
// prints Symbol(my cat)

The “Symbol” Function Cannot be Used with the operator “new”

Symbol() cannot be used with new.

// new Symbol();
// TypeError: Symbol is not a constructor

The “Symbol” Function Return a Unique Symbol, Always

// Symbol() always returns a unique symbol
console.log((Symbol() === Symbol()) === false);

typeof Symbol

typeof Operator on symbol value returns string "symbol". [see Value Types]

console.log(typeof Symbol() === "symbol");
console.log(typeof Symbol("abc") === "symbol");

Using Symbol as Property Key

Before JS2015, property key can only be string type. In JS2015, property key can be either a string type or symbol type.

Property key that is string is called property name
Property key that is symbol is called property symbol

The symbol value is designed to be keys for properties. Because user-created symbol values are unique, this means property key collision cannot happen. This lets you add properties to any object of any libraries and don't have to worry about property key collision.

💡 TIP: you normally should assign a symbol value to a variable, otherwise you cannot access the symbol, unless you use numerical index that relies on the order of properties.

Use Bracket Notation to Access Symbol Property

Use bracket notation to access property symbol. Like this:

obj[symbol]
obj[variable_of_symbol]

// add a symbol key property
const ss = Symbol();
const jj = {};
jj[ss] = 3;
console.log(jj[ss] === 3);

// add a symbol key property, via symbol value directly
const jj = {};
jj[Symbol()] = 4;

console.log(jj[Object.getOwnPropertySymbols(jj)[0]] === 4);

Symbol Property in Object Literal Expression

You can use symbol property key in object literal expression (New in JS2015.), like this:

const obj = {[symbol]:value}

[see ES2015 Object Literal Expression Extensions]

// use of symbol key in object literal expression
const jj = { [Symbol()]: 3 };

console.log(jj[Object.getOwnPropertySymbols(jj)[0]] === 3);

Symbol Properties Are Usually Ignored

Symbol properties are usually ignored by constructs that access properties.

for-in Loop ignore symbol key properties.
Object.keys ignores symbol key properties.
Object.getOwnPropertyNames ignores symbol key properties.
console.log(obj) may or may not print symbol properties of obj.

[see List Properties]

const ss = Symbol();
const jj = { [ss]: 4 };

// exists
console.log(jj.hasOwnProperty(ss));

// symbol key properties are ignored by many constructs
console.log(Object.keys(jj).length === 0);
console.log(Object.getOwnPropertyNames(jj).length === 0);

Check Symbol Property Existence

Check Property Existence

List Symbol Keys

Convert Symbol to String

To convert symbol to string, do

sym.toString()

💡 TIP: "some " + symbol results TypeError. you must use "some " + symbol.toString()

🛑 WARNING: symbols without description all become "Symbol()". You cannot distinguish them.

// convert a symbol value to string

const ss = Symbol("xx");

console.log(ss.toString() === "Symbol(xx)");

JavaScript, Symbol

BUY ΣJS JavaScript in Depth