Last modified: Jul 22, 2026

JS Symbol Variables Guide

JavaScript has seven primitive data types. Six are well-known: string, number, boolean, null, undefined, and bigint. The seventh is Symbol. It was introduced in ES6. Symbols are unique and immutable. They are often used as object property keys. This guide explains everything you need to know about JavaScript Symbol variables.

Symbols are not like other primitives. Every Symbol value is unique. Even if you create two Symbols with the same description, they are different. This makes them perfect for avoiding property name collisions.

In this article, you will learn how to create Symbols. You will see how to use them as object keys. You will also discover global Symbols and well-known Symbols. Let's start.

What Is a Symbol?

A Symbol is a primitive value. You create it by calling the Symbol() function. You do not use the new keyword. Symbol() returns a unique value each time.

 
// Creating a Symbol
const sym1 = Symbol();
const sym2 = Symbol();
console.log(sym1 === sym2); // false


false

Each Symbol is guaranteed to be unique. This is the core feature. You can add an optional description. The description is for debugging. It does not affect uniqueness.

 
// Symbol with description
const symA = Symbol('alpha');
const symB = Symbol('alpha');
console.log(symA === symB); // false


false

Using Symbols as Object Keys

Symbols are great for object property keys. They are unique. They cannot be accidentally overwritten. This is useful for libraries or large codebases.

 
// Using Symbol as object key
const id = Symbol('id');
const user = {
  name: 'Alice',
  [id]: 12345
};
console.log(user[id]); // 12345


12345

Notice the square brackets. You must use them to set a Symbol property. Without them, id would become a string key.

Symbol keys are not enumerable. They do not appear in for...in loops. They are also hidden from Object.keys(). This makes them private-like. But they are not truly private. You can still access them with Object.getOwnPropertySymbols().

 
// Accessing Symbol keys
const symId = Symbol('id');
const obj = { name: 'Bob', [symId]: 999 };
console.log(Object.keys(obj)); // ['name']
console.log(Object.getOwnPropertySymbols(obj)); // [ Symbol(id) ]


['name']
[ Symbol(id) ]

Global Symbols and the Symbol Registry

Sometimes you need to share Symbols across your application. JavaScript provides a global Symbol registry. Use Symbol.for() to create or retrieve a Symbol by a string key.

 
// Global Symbol registry
const globalSym1 = Symbol.for('app.user');
const globalSym2 = Symbol.for('app.user');
console.log(globalSym1 === globalSym2); // true


true

Symbol.for() checks the registry first. If a Symbol with that key exists, it returns it. If not, it creates a new one. This ensures uniqueness across modules.

To get the key from a global Symbol, use Symbol.keyFor().

 
// Getting the key
const sym = Symbol.for('myKey');
console.log(Symbol.keyFor(sym)); // 'myKey'


'myKey'

Well-Known Symbols

JavaScript has built-in Symbols. They are called well-known Symbols. They let you customize object behavior. For example, Symbol.iterator makes an object iterable.

 
// Using Symbol.iterator
const myRange = {
  from: 1,
  to: 3,
  [Symbol.iterator]() {
    let current = this.from;
    const last = this.to;
    return {
      next() {
        if (current <= last) {
          return { value: current++, done: false };
        } else {
          return { done: true };
        }
      }
    };
  }
};
for (const num of myRange) {
  console.log(num);
}


1
2
3

Other well-known Symbols include Symbol.toStringTag, Symbol.hasInstance, and Symbol.toPrimitive. They are powerful tools for metaprogramming.

Symbols Are Not Strings

Do not confuse Symbols with strings. Symbols are unique. Strings are not. You cannot implicitly convert a Symbol to a string. You must call Symbol.prototype.toString() or use the description.

 
// Symbol to string conversion
const sym = Symbol('test');
console.log(sym.toString()); // 'Symbol(test)'
console.log(sym.description); // 'test'


Symbol(test)
test

If you try to concatenate a Symbol with a string, you get an error. Always convert explicitly.

Practical Use Cases

Symbols are useful in many scenarios. They help avoid naming conflicts. They are perfect for adding metadata to objects. They are also used in frameworks and libraries.

For example, you can create a private-like property for internal state.

 
// Private-like property
const _private = Symbol('private');
class MyClass {
  constructor(value) {
    this[_private] = value;
  }
  getValue() {
    return this[_private];
  }
}
const instance = new MyClass(42);
console.log(instance.getValue()); // 42
console.log(instance._private); // undefined


42
undefined

Symbols also help when you need to add a unique key to an object. This is common in plugins or extensions.

For more on how variables behave in different contexts, see our JavaScript Variable Scope Explained guide.

Symbols vs Other Primitives

Symbols are different from strings and numbers. They are not auto-converted. They are not equal unless they are the same Symbol. They are immutable. Use them when you need guaranteed uniqueness.

If you are working with strings, check our JavaScript Variable as String Guide for comparison.

Common Mistakes

Beginners often try to use new Symbol(). This throws an error. Always use Symbol() without new.

 
// Wrong way
// const sym = new Symbol(); // TypeError
// Correct way
const sym = Symbol();

Another mistake is forgetting square brackets for Symbol keys. Without brackets, the key becomes a string.

 
// Wrong way
const sym = Symbol('key');
const obj = {};
obj.sym = 'value'; // string key 'sym', not Symbol
console.log(obj[sym]); // undefined
// Correct way
obj[sym] = 'value';
console.log(obj[sym]); // 'value'


undefined
'value'

Also, remember that Symbols are not enumerable in for...in. Use Object.getOwnPropertySymbols() to find them.

For more on variable naming, see our JavaScript Variable Naming Rules article.

Conclusion

JavaScript Symbol variables are unique and immutable. They are perfect for object property keys. They prevent naming collisions. They also enable metaprogramming with well-known Symbols. Use Symbol() for local uniqueness. Use Symbol.for() for global sharing. Remember to use square brackets for Symbol keys. Symbols are a powerful tool in your JavaScript toolkit. Practice with the examples above. You will soon master them.

Recent Tutorials: