Codectionary / Developer documentation / JavaScript

Symbols

Symbol is a primitive type that creates unique, immutable identifiers. Every Symbol() call produces a completely unique value, even with the same description, which makes them useful as object property keys that are guaranteed not to collide with other keys - including string keys or other symbols. They are also used internally by JavaScript for things like Symbol.iterator.

Syntax

const sym = Symbol("description");

Examples

Creating Unique Symbols

Every symbol is unique, even with an identical description.

const sym1 = Symbol("id");
const sym2 = Symbol("id");

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

Symbols as Object Keys

Using a symbol to create a property that will not collide with string keys or be picked up by normal enumeration.

const id = Symbol("id");

const user = {
  name: "Alice",
  [id]: 12345 // a symbol-keyed property
};

console.log(user[id]); // 12345
console.log(Object.keys(user)); // ["name"] - the symbol key is skipped
console.log(JSON.stringify(user)); // {"name":"Alice"} - symbols are also skipped here

Best practices

  • Use symbols when you need a guaranteed-unique property key that will not accidentally collide with other properties
  • Remember symbol-keyed properties are hidden from Object.keys(), for...in, and JSON.stringify() - useful for "metadata" style properties
  • Do not overuse symbols for everyday object keys - plain string keys are simpler and sufficient for the vast majority of cases
  • Use well-known symbols like Symbol.iterator when you specifically need to customize how an object behaves with built-in language features

Runtime & versions

Browsers and JavaScript runtimes. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

ECMAScript specification

Specifications & further reading