Javascript Symbol And How To Use It

Anton Ioffe - November 1st 2023 - 9 minutes read

In this comprehensive exploration of JavaScript Symbols - the less explored and sometimes misunderstood feature of ECMAScript 2015, we delve into the depths of symbols, examining their nature, creation, and unconventional use as object properties. Going further, we'll unearth the potent power of symbols in preventing identifier clashes, crafting 'hidden' properties as well as simulating private properties in JavaScript. Moreover, we reveal the mysteries behind built-in and global symbols provided by the Symbol object. Lastly, we won’t leave you stranded amid possible symbol-related coding mistakes. The article offers corrective strategies and best-practices, with a comparative take on symbols as used in other programming paradigms - all in an effort to elevate your understanding and application of JavaScript Symbols in modern web development. Whether you're looking to mitigate name clashes in your libraries or wanting to create truly private properties in JavaScript, this reading treasure brings you practical insights with real-life coding examples. Dive in, and emerge with a master's command over JavaScript symbols!

Understanding JavaScript Symbols: The Basics, Creation, and Usage as Object Properties

Understanding JavaScript Symbols: The Basics

Symbols, a primitive data type unique to JavaScript ES6, come in two flavors: user-created and well-known (or global). By calling the Symbol() function, you can create your own symbol. Every symbol is utterly unique, making symbols rather handy when you need unique keys for object properties - a boon in metaprogramming where the risks of naming collisions are significant.

Symbols as Object Properties

When it comes to creating keys for object properties, it's a task only strings or symbols can handle. Any other types, like a Number, are quickly auto-converted to strings. So, while strings are commonly used, uniquely using symbols as keys could potentially add another layer of functionality. Here's how you can create a symbol and use it as a key within an object:

const obj = {};
const sym = Symbol();
obj[sym] = 'foo'; = 'bar';
console.log(obj); // { bar: 'bar', [Symbol()]: 'foo' }
console.log(sym in obj); // true
console.log(obj[sym]); // 'foo'

In this code snippet, sym, defined as a symbol, is placed as a property to object obj with the value 'foo'. Although the symbol property isn't readily apparent when we log the entire object, the statement sym in obj returns true, confirming that sym indeed exists as a property in obj.

Maintaining Backward Compatibility with Symbols

Symbols also uphold backward compatibility. They remain unseen when using the Object.keys(obj) method to avoid confusing older codes that may be oblivious to symbols, as the following snippet shows:

console.log(Object.keys(obj)); // ['bar']

Although the symbol property isn't listed, symbols have a place of their own outside the conventional enumeration which might make it seem like they are providing 'private' properties in JavaScript, a characteristic that many other languages possess but JavaScript lacks.

Symbols and Object Keys

In the context of object properties, JavaScript symbols provide a unique key identity preventing any potential naming conflicts. Though symbols are non-enumerable and don't appear in Object.keys(), or for…in loops for that matter, they are accessible and can be retrieved using Object.getOwnPropertySymbols(). Here is how to do it:

let symbolProperties = Object.getOwnPropertySymbols(obj);
console.log(symbolProperties); // [Symbol()]
console.log(obj[symbolProperties[0]]); // 'foo'

This methodology ensures that while symbols remain hidden during typical object property enumeration, they aren't entirely private or inaccessible. Symbols as object keys lend unique properties to the object, emphasize metaprogramming practices, and maintain compatibility with older codes. So, the next time you need unique keys for properties, consider JavaScript symbols.

Symbols in JavaScript: Preventing Name Clashes, Creating 'Hidden' Properties, and Simulating Private Properties

In the modern JavaScript development setting, symbols serve a critical role in protecting property names from collisions, specifically when multiple libraries attempt to add properties to objects concurrently. When libraries aim to attach important metadata to objects without tampering with the object's existing data, utilizing symbols as property keys effectively prevents name conflicts. This feature is mainly due to the uniqueness of symbols, ensuring no two identical symbols can exist, hence avoiding possible name clashes. Witness how symbols can be beneficial in the following code block which represents two different libraries employing symbols to append metadata without interfering with one another:

const LibraryA = Symbol('LibraryA');
const LibraryB = Symbol('LibraryB');

let someSharedObject = {
  existingProperty: 'This data is important'

someSharedObject[LibraryA] = 'Some metadata from Library A';
someSharedObject[LibraryB] = 'Some metadata from Library B';
// There's now no way these properties can interfere with each other - or the original object properties

Another insightful product of using symbols is the creation of 'hidden' properties. A symbolic property does not show up in a loop, thereby averting accidental processing alongside standard properties. This aspect enables the strategic concealment of properties in an object that are accessible to a specific part of the code, much like creating 'shadow' or 'hidden' attributes. Visit the code below to see this in action:

const hiddenProperty = Symbol('hiddenProperty');
let myObject = {
  visibleProperty: 'You can see me'

myObject[hiddenProperty] = 'You cannot see me';
console.log(myObject); // Only shows { visibleProperty: 'You can see me' }

Moreover, symbols pose a powerful approach to simulate private properties in JavaScript objects. There is a common desire to instantiate truly private fields or properties in JavaScript, especially with the adoption of a more object-oriented approach in modern projects. Though there has been an introduction of private fields in JavaScript classes recently, symbols can act as a useful tool for simulating this 'privateness' in object properties. Despite symbols not being fully private themselves (as one can gain access via certain reflective methods), they help simulate private features by ensuring other parts of code, which don't explicitly have access to the symbols, cannot inadvertently access or overwrite these properties. For instance, in the absence of a direct reference to a symbol, it is tough to interact with a symbol-keyed property, as demonstrated below:

let obj = {};
let privateProperty = Symbol('privateProperty');

obj[privateProperty] = 'This is a somewhat private property';

console.log(obj[privateProperty]); // 'This is a somewhat private property'
console.log(obj['privateProperty']); // undefined

So while symbols offer a handy toolset in JavaScript, they are easily overlooked. As demonstrated, they can be cleverly utilized to prevent name collisions—critical when several libraries are trying to interact with the same objects. They can also help create 'hidden' properties and approximate private properties, both of which can come in handy when dealing with large, complex codebases. But, remember, symbols are not absolutely hidden or private. Certain methods can reveal them, such as Object.getOwnPropertySymbols(obj) or Reflect.ownKeys(obj), displaying all keys, including symbolic ones. Therefore, when you plan to implement symbols, you need to remain mindful of these nuances.

Mastering Built-In and Global Symbols in JavaScript

To start, it is worth noting that the JavaScript language comes built-in with several global symbols that you can access using properties of the Symbol object. These symbols are commonly referred to as "well-known symbols", and they make up a subset of the built-in symbols JavaScript provides.

One such well-known symbol is Symbol.iterator. This symbol allows you to customize the behavior of an object when it's looped over in a for...of loop, or when it's used with the spread (...) operator. Let's take a look at a code example:

const myArray = [1, 2, 3];
const iterator = myArray[Symbol.iterator]();

console.log(; // {value: 1, done: false}
console.log(; // {value: 2, done: false}
console.log(; // {value: 3, done: false}
console.log(; // {done: true}

In this example, we retrieve the default iterator from the myArray instance using Symbol.iterator, allowing us to manually iterate over the elements of the array.

Another well-known symbol is Symbol.unscopables. Its main purpose is maintaining backward compatibility with older JavaScript versions, providing a way to exclude object properties from with statement bindings.

let myArray = [1, 2, 3]; = 'hello';

with (myArray) {
  console.log(foo); // prints 'hello'

myArray[Symbol.unscopables] = {
  foo: true

with (myArray) {
  console.log(foo); // ReferenceError: foo is not defined

In the first with block, the foo property is accessible. But after setting foo as an unscopable property, it is no longer available within the with block: trying to access it will throw a ReferenceError.

Finally, there are global symbols that can be created using Symbol.for(key). This function first searches for a symbol with the given key in the global symbol registry. If a symbol with this key is found, it is returned. Otherwise, a new symbol is created, added to the global symbol registry under the given key, and then returned.

const mySymbol = Symbol.for('myKey');

// checking if mySymbol was indeed added to the global symbol registry
console.log(Symbol.keyFor(mySymbol)); // prints 'myKey'

const otherSymbol = Symbol('myKey');

// checking if otherSymbol was added to the global symbol registry
console.log(Symbol.keyFor(otherSymbol)); // prints undefined

// otherSymbol is a completely new symbol, despite having the same description as mySymbol
console.log(mySymbol === otherSymbol); // prints false

In the above code, mySymbol is added to the global symbol registry; we verify this by retrieving its key using Symbol.keyFor(). otherSymbol, which was created using Symbol(), is not added to the global symbol registry, and Symbol.keyFor(otherSymbol) returns undefined. Despite the descriptions of both symbols being the same ('myKey'), the symbols themselves are unique and not equal to each other.

In conclusion, JavaScript's built-in and globally-unique symbols provide flexible strategies for working with objects and classes, and are a potent tool to have in your JavaScript toolbox. They serve a variety of use cases, from altering default method behaviors to providing nearly-private object properties.

Avoiding and Correcting Mistakes Using JavaScript Symbols: Performance, Best-practices, and Comparative Analysis

A common coding mistake while using JavaScript symbols is treating symbols as strings. Due to their unique nature, symbols cannot be coerced into strings without triggering a TypeError. Take the following example where "symbol" addition to the string throws a TypeError:

let uniqueSymbol = Symbol('example');
console.log('My ' + uniqueSymbol); // Throws TypeError: Cannot convert a Symbol value to a string

The correct approach is to explicitly cast the symbol into string format when performing string concatenation:

let uniqueSymbol = Symbol('example');
console.log('My ' + uniqueSymbol.toString()); // Outputs: 'My Symbol(example)'

Now let's pivot to performance considerations. Symbols, unlike other primitives in JavaScript like strings or numbers, consume a lot less memory. This makes them highly efficient when dealing with large datasets as unique identifiers. Furthermore, using symbols as object keys enhances the lookup and retrieval process, thereby reducing time complexity from O(n) to O(1) in key-value pair mappings. However, be mindful that, due to their unique and non-enumerable nature, symbols can potentially impede the readability and reusability of the source code if not adequately documented. By compartmentalizing and isolating application-specific logic, symbols enhance the modularity of your codebase.

On the best-practices front, when registering global symbols, a mistake often lies in assuming that the description in Symbol.for() serves a purpose in logical comparison. Since descriptions merely serve as identifiers for debugging, it's a misconception to assume that they influence symbol equality. Have a glance at the following error:

let globalSymbol1 = Symbol.for('global');
let globalSymbol2 = Symbol.for('GLOBAL');
console.log(globalSymbol1 === globalSymbol2); // Outputs: false

The correction is to use the same description for creating two symbols as Symbol.for() is case-sensitive and the descriptions do not affect the equality:

let globalSymbol1 = Symbol.for('global');
let globalSymbol2 = Symbol.for('global');
console.log(globalSymbol1 === globalSymbol2); // Outputs: true

Comparatively, languages like Ruby also incorporate symbols as a datatype, but with differences. In Ruby, symbols are immutable strings that consume less memory and provide faster comparisons. Unlike JavaScript, Ruby symbols do not aid in creating private or hidden object properties. Subsequently, JavaScript symbols offer more application-wide utility due to their unique identification and compatibility with existing code, thereby ensuring JavaScript's more flexible approach to symbols in its dynamically-typed language ecosystem.


In this comprehensive article about JavaScript Symbols, the author explores the nature, creation, and usage of symbols in modern web development. Symbols are unique keys for object properties, offering benefits such as preventing name clashes, creating hidden properties, and simulating private properties. The article also covers built-in and global symbols provided by the Symbol object, as well as common mistakes and best practices when working with symbols. To challenge readers, they are encouraged to think about how symbols can be used to enhance the modularity and performance of their code, and to consider the differences between JavaScript symbols and symbols in other programming languages.

Don't Get Left Behind:
The Top 5 Career-Ending Mistakes Software Developers Make
FREE Cheat Sheet for Software Developers