Symbols

Syntax

const sym = Symbol("description");

Examples

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

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

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

At a glance

Purpose

Application logic and interaction

File extension

.js · .mjs

Runs in

Browsers and JavaScript runtimes

Usually used with

HTML, CSS and Web APIs

Specifications & further reading

• ECMAScript specification

Related JavaScript documentation