JavaScript Symbol Guide

Symbols are unique, immutable primitive values used for property keys and metaprogramming. Here's how to use them effectively.

Basic Usage#

// Create unique symbols
const sym1 = Symbol();
const sym2 = Symbol();

console.log(sym1 === sym2); // false - always unique

// With description (for debugging)
const id = Symbol('id');
const name = Symbol('name');

console.log(id.description); // 'id'
console.log(String(id));     // 'Symbol(id)'

// Symbols as property keys
const user = {
  [id]: 123,
  [name]: 'John',
  email: 'john@example.com',
};

console.log(user[id]);   // 123
console.log(user[name]); // 'John'

Hidden Properties#

// Symbols are not enumerable by default
const secret = Symbol('secret');

const obj = {
  visible: 'I am visible',
  [secret]: 'I am hidden',
};

// Not included in iterations
console.log(Object.keys(obj));           // ['visible']
console.log(JSON.stringify(obj));        // '{"visible":"I am visible"}'
for (const key in obj) console.log(key); // 'visible'

// But accessible directly
console.log(obj[secret]); // 'I am hidden'

// Get symbol properties
console.log(Object.getOwnPropertySymbols(obj)); // [Symbol(secret)]
console.log(Reflect.ownKeys(obj));              // ['visible', Symbol(secret)]

Symbol.for() - Global Registry#

// Create/retrieve symbols from global registry
const globalSym1 = Symbol.for('app.id');
const globalSym2 = Symbol.for('app.id');

console.log(globalSym1 === globalSym2); // true - same symbol

// Get key from symbol
console.log(Symbol.keyFor(globalSym1)); // 'app.id'

// Regular symbols are not in registry
const localSym = Symbol('local');
console.log(Symbol.keyFor(localSym)); // undefined

// Cross-realm symbol sharing
// Symbol.for() returns same symbol across iframes, workers, etc.

Well-Known Symbols#

// Symbol.iterator - make objects iterable
const range = {
  start: 1,
  end: 5,

  [Symbol.iterator]() {
    let current = this.start;
    const end = this.end;

    return {
      next() {
        if (current <= end) {
          return { value: current++, done: false };
        }
        return { done: true };
      },
    };
  },
};

console.log([...range]); // [1, 2, 3, 4, 5]

for (const num of range) {
  console.log(num); // 1, 2, 3, 4, 5
}

Symbol.toStringTag#

// Customize Object.prototype.toString() result
class MyClass {
  get [Symbol.toStringTag]() {
    return 'MyClass';
  }
}

const obj = new MyClass();
console.log(Object.prototype.toString.call(obj)); // '[object MyClass]'
console.log(obj.toString()); // '[object MyClass]'

// Built-in examples
console.log(Object.prototype.toString.call(new Map()));     // '[object Map]'
console.log(Object.prototype.toString.call(new Set()));     // '[object Set]'
console.log(Object.prototype.toString.call(new Promise(() => {}))); // '[object Promise]'

Symbol.toPrimitive#

// Customize type coercion
class Money {
  constructor(amount, currency) {
    this.amount = amount;
    this.currency = currency;
  }

  [Symbol.toPrimitive](hint) {
    switch (hint) {
      case 'number':
        return this.amount;
      case 'string':
        return `${this.currency}${this.amount}`;
      default: // 'default'
        return this.amount;
    }
  }
}

const price = new Money(100, '$');

console.log(+price);           // 100 (number hint)
console.log(`${price}`);       // '$100' (string hint)
console.log(price + 50);       // 150 (default hint)
console.log(price == 100);     // true (default hint)

Symbol.hasInstance#

// Customize instanceof behavior
class MyArray {
  static [Symbol.hasInstance](instance) {
    return Array.isArray(instance);
  }
}

console.log([] instanceof MyArray);     // true
console.log([1, 2] instanceof MyArray); // true
console.log({} instanceof MyArray);     // false

// Practical example
class Validator {
  constructor(predicate) {
    this.predicate = predicate;
  }

  static [Symbol.hasInstance](value) {
    return typeof value === 'string' && value.length > 0;
  }
}

console.log('hello' instanceof Validator); // true
console.log('' instanceof Validator);      // false

Symbol.species#

// Control constructor for derived objects
class MyArray extends Array {
  static get [Symbol.species]() {
    return Array; // Methods like map() return plain Array
  }
}

const myArr = new MyArray(1, 2, 3);
const mapped = myArr.map((x) => x * 2);

console.log(myArr instanceof MyArray);    // true
console.log(mapped instanceof MyArray);   // false
console.log(mapped instanceof Array);     // true

Symbol.isConcatSpreadable#

// Control Array.concat() behavior
const arr = [1, 2];
const spreadable = {
  0: 3,
  1: 4,
  length: 2,
  [Symbol.isConcatSpreadable]: true,
};

console.log(arr.concat(spreadable)); // [1, 2, 3, 4]

// Prevent array spreading
const noSpread = [5, 6];
noSpread[Symbol.isConcatSpreadable] = false;

console.log(arr.concat(noSpread)); // [1, 2, [5, 6]]

Symbol.match/replace/search/split#

// Custom string matching
class StartsWithMatcher {
  constructor(prefix) {
    this.prefix = prefix;
  }

  [Symbol.match](string) {
    return string.startsWith(this.prefix);
  }

  [Symbol.replace](string, replacement) {
    if (string.startsWith(this.prefix)) {
      return replacement + string.slice(this.prefix.length);
    }
    return string;
  }
}

const matcher = new StartsWithMatcher('Hello');

console.log('Hello World'.match(matcher));           // true
console.log('Hello World'.replace(matcher, 'Hi'));   // 'Hi World'
console.log('Goodbye'.match(matcher));               // false

Private-like Properties#

// Symbols for pseudo-private properties
const _private = Symbol('private');

class Counter {
  constructor() {
    this[_private] = 0;
  }

  get count() {
    return this[_private];
  }

  increment() {
    this[_private]++;
  }
}

const counter = new Counter();
counter.increment();
console.log(counter.count);     // 1
console.log(counter[_private]); // 1 (if you have the symbol)
console.log(Object.keys(counter)); // []

Plugin/Extension Keys#

// Use symbols for plugin properties to avoid conflicts
const pluginData = Symbol('pluginData');
const pluginInit = Symbol('pluginInit');

function installPlugin(obj, data) {
  obj[pluginData] = data;
  obj[pluginInit] = true;
}

function getPluginData(obj) {
  if (!obj[pluginInit]) {
    throw new Error('Plugin not initialized');
  }
  return obj[pluginData];
}

const myObj = { name: 'Test' };
installPlugin(myObj, { version: '1.0' });

console.log(myObj.name);              // 'Test'
console.log(getPluginData(myObj));    // { version: '1.0' }
console.log(Object.keys(myObj));      // ['name']

Type Checking with Symbols#

// Custom type identification
const TYPE = Symbol('type');

class Dog {
  static [TYPE] = 'Dog';
  [TYPE] = 'Dog';
}

class Cat {
  static [TYPE] = 'Cat';
  [TYPE] = 'Cat';
}

function getType(obj) {
  return obj?.[TYPE] ?? 'Unknown';
}

console.log(getType(new Dog())); // 'Dog'
console.log(getType(new Cat())); // 'Cat'
console.log(getType({}));        // 'Unknown'

Best Practices#

Usage:
✓ Unique property keys
✓ Hidden metadata
✓ Well-known symbol customization
✓ Avoiding name collisions

Global Registry:
✓ Use Symbol.for() for shared symbols
✓ Use descriptive key names
✓ Namespace keys (e.g., 'myapp.feature')
✓ Check Symbol.keyFor() when needed

Well-Known Symbols:
✓ Symbol.iterator for iterables
✓ Symbol.toStringTag for debugging
✓ Symbol.toPrimitive for coercion
✓ Symbol.hasInstance for instanceof

Avoid:
✗ Symbols for true privacy (use #private)
✗ Overusing symbols
✗ Forgetting symbols are not enumerable
✗ Converting symbols to strings accidentally

Symbols provide unique identifiers for object properties and enable metaprogramming through well-known symbols. Use them for hidden properties, avoiding naming collisions in libraries, and customizing object behavior like iteration and type coercion. The global registry (Symbol.for) enables cross-realm symbol sharing. While not truly private, symbols are hidden from most iteration methods, making them useful for metadata and internal properties.