JS: Symbol Tutorial

By Xah Lee. Date: . Last updated: .

New in ES2015.

  1. Symbol is a primitive type. [see JS: Primitive Value]
  2. Symbol is the set of all non-string values that may be used as the key of a object property.
  3. The purpose of symbol is to avoid property name collision.
  4. Each symbol value is unique and immutable.
  5. Each symbol value has an associated value called “Description”, usually denoted in document as [[Description]]. Its value is either undefined or a string. This [[Description]] cannot be changed once created.

Create Symbol

Symbol() → return a symbol.

Symbol(description) → return a symbol with description string description.

The description is a printed representation of the symbol, mostly for debugging purposes. The description is used when you convert symbol to string. Note: 2 symbols with same description are still different symbols.

// creating symbol

const x = Symbol();
const y = Symbol();
const z = Symbol("my cat");

console.log(x); // prints Symbol()
console.log(y); // prints Symbol()
console.log(z); // prints Symbol(my cat)

[see JS: const Declaration]

「Symbol()」 Cannot be Used with 「new」

Symbol() cannot be used with new.

new Symbol();
// TypeError: Symbol is not a constructor

Symbol() Return a Unique Symbol, Always

// Symbol() always returns a unique symbol
console.log( Symbol() === Symbol() ); // false

typeof Symbol

typeof on symbol value returns string "symbol".

console.log( typeof Symbol() === "symbol" ); // true
console.log( typeof Symbol("abc") === "symbol" ); // true

[see JS: Value Types]

Using Symbol as Property Key

Before ES2015, property key can only be string type. In ES2015, property key can be either a string type or symbol type.

The symbol value is designed to be keys for properties. Because symbol values are unique, this means property key collision cannot happen.

You can add properties to objects in libraries and don't have to worry about property key collision.

Use Bracket Notation to Access Symbol Property

Use bracket notation to access property symbol. Like this:

// adding a symbol key property
const x = Symbol();
const obj = {};
obj[x] = 3;
console.log ( obj[x] === 3 ); // true
// adding a symbol key property, via symbol value directly
const obj = {};
obj[Symbol()] = 4;

console.log(
 obj[Object.getOwnPropertySymbols(obj)[0]] === 4
); // true

Note: you cannot use dot notation for property keys that are symbol. [see JS: Property Dot Notation / Bracket Notation]

Symbol Property in Object Literal Expression

You can use symbol property key in object literal expression (New in ES2015.), like this:

const obj = {[expression]:value}

// use of symbol key in object literal expression
const obj = {[Symbol()]:3};

console.log ( obj ); // { [Symbol()]: 3 };

[see JS: ES2015 Object Literal Expression Extensions]

Symbol Properties Are Usually Ignored

Symbol properties are usually ignored by constructs that access properties.

console.log(obj) may or may not print symbol properties of obj.

[see JS: List Properties]

const obj = {[Symbol()]:4};

console.log (
 obj[(Object.getOwnPropertySymbols ( obj ))[0]] === 4
); // true
// exists

// symbol key properties are ignored by many constructs
console.log(Object.keys(obj)); // []
console.log(Object.getOwnPropertyNames(obj)); // []
for (let p in obj) { console.log("yes"); } // prints nothing

Check Symbol Property Existence

obj.hasOwnProperty(key)

[see JS: Object.prototype.hasOwnProperty]

To check if a property key is in a object obj's prototype chain (including if it's its own property), use one of:

[see JS: Check Property Existence]

List Symbol Keys

Object.getOwnPropertySymbols(obj) → return a array of symbol keys of obj.

[see JS: Object.getOwnPropertySymbols]

Reflect.ownKeys(obj) → return a array of all (string and symbol) property keys.

[see JS: Reflect.ownKeys]

Convert Symbol to String

To convert symbol to string, do

sym.toString()

Note: "some " + symbol results TypeError. you must use "some " + symbol.toString()

const ss = Symbol("cat");
console.log( ss.toString() === "Symbol(cat)"); // true
console.log( "my " + ss.toString() === "my Symbol(cat)"); // true

// console.log( "my " + ss);
// TypeError: Cannot convert a Symbol value to a string

JS Symbol

  1. JS: Symbol Tutorial
  2. JS: Symbol Object
  3. JS: Symbol.prototype

JS Object Property

  1. Property Overview
  2. Property Key
  3. Dot vs Bracket Notation
  4. Create/Delete Property
  5. Get/Set Property
  6. Check Property Existence
  7. Access Property
  8. List Properties
  9. Property Attributes
  10. Getter/Setter
  11. Property Descriptor
  12. Symbol
Liket it? I spend 2 years writing this tutorial. Help me spread it. Tell your friends. Or, Put $5 at patreon.

Or, Buy JavaScript in Depth

If you have a question, put $5 at patreon and message me.

JavaScript in Depth

Basics

  1. JavaScript Basics
  2. true, false
  3. Operators
  4. Branch Control
  5. Loop
  6. Array Basics
  7. Object Basics
  8. RegExp Basics

Variable

  1. Value Types
  2. let
  3. const
  4. var
  5. var Order
  6. var Scope
  7. Global Variable
  8. Destructuring Assignment

String

  1. String Overview
  2. Template String
  3. Char, Code Unit, Codepoint
  4. String Escape Sequence
  5. Unicode Escape Sequence

Function

  1. Define Function
  2. Arrow Function ⭐
  3. Function Params
  4. “arguments” Object
  5. Rest Params ⭐
  6. Arg Default Value ⭐
  7. Arg Destructure ⭐
  8. f Declaration vs Expression
  9. Closure
  10. f call apply bind
  11. Functional Programing

Object Property

  1. Property Overview
  2. Property Key
  3. Dot vs Bracket Notation
  4. Create/Delete Property
  5. Get/Set Property
  6. Check Property Existence
  7. Access Property
  8. List Properties
  9. Property Attributes
  10. Getter/Setter
  11. Property Descriptor
  12. Symbol

Object and Inheritance

  1. Object Overview
  2. Object Type
  3. Find Object's Type
  4. Prototype Chain
  5. Create Object
  6. Object Literal Expr
  7. Create Object with Parent X
  8. Get/Set Parent
  9. Show Prototype Chain
  10. Prevent Adding Property
  11. Clone Object
  12. Test Object Equality
  13. Add Method to Prototype

Array

  1. Understand JS Array
  2. Create Array
  3. Sparse Array
  4. Array-Like Object
  5. Array How-To

Class

  1. “this” Binding
  2. What's Constructor?
  3. Property Key "prototype"
  4. Operator “new”
  5. Operator “instanceof”
  6. Property Key “constructor”
  7. Class
  8. Keyword “extends”
  9. Keyword “super”

Iterable ⭐

  1. Interface
  2. Iterable
  3. Iterator
  4. Iterator Prototype
  5. for-of Loop
  6. Spread Operator
  7. Generator
  8. Generator Function

Misc

  1. Set Object
  2. Map Object
  3. Try Catch Throw Finally
  4. Import/Export
  5. Promise
  6. Proxy
  7. ES2015 Features
  8. How to Convert ES5 to ES2015
  9. Style Guide
  10. Semicolon Rules
  11. Exclamation Before Function
  12. How to Determine Strict Mode?
  13. x.y.z Associativity
  14. Function Chain
  15. Random Number, Range, Integer, Element
  16. Timing JS Code
  17. Range Function for Array
  18. Random Array Element, Randomize Array
  19. Tagged Template String
  20. String to Number
  21. Format Number

Object Reference

  1. the Global Object
  2. Object 🙼 Object.prototype
  3. Array 🙼 Array.prototype
  4. Function 🙼 Function.prototype
  5. String 🙼 String.prototype
  6. RegExp 🙼 RegExp.prototype 🙼 RegExp Syntax
  7. Date 🙼 Date.prototype
  8. Set ⭐🙼 Set.prototype
  9. Map ⭐🙼 Map.prototype
  10. JSON
  11. Math
  12. Reflect
  13. Symbol ⭐🙼 Symbol.prototype
  14. Number 🙼 Number.prototype
  15. Boolean 🙼 Boolean.prototype

DOM How-To

  1. Basic DOM Methods
  2. Get Elements by ID, Tag, Name, Class, CSS Selector
  3. Change CSS
  4. Change Node Content
  5. Create/Insert Node
  6. Remove Node
  7. Get Element's Attribute Value
  8. Set Element's Attribute Value
  9. Remove Element's Attribute Value
  10. List/Add/Remove Class Attribute
  11. Add/Remove Event Handler
  12. Navigate DOM Tree

DOM Overview

  1. Browser Window Object, Document Object Model
  2. Intro to Event-Based Programing
  3. JavaScript Load Order
  4. What is Live Object
  5. NodeList vs HTMLCollection
  6. DOM: Whitespace Nodes

Basic DOM Methods

  1. Basic DOM Methods
  2. Node Type, Name, Value
  3. Navigate DOM Tree

HTML Form

  1. HTML Form
  2. Visit URL in a New Window
  3. Instant Field Validation
  4. Input Field Validation
  5. HTML: Input Range Slider

DOM How To

  1. Encode URL, Escape String
  2. Browser Info, Navigator Object
  3. Get URL (window.location)
  4. Web Cookies
  5. Web Storage
  6. Find Window Width
  7. Find Element Width
  8. WebSocket

Web Scripting Examples

  1. Disable Right Click
  2. document.write
  3. Image Rollover
  4. Pop-up New Window
  5. Digital Clock
  6. Stopwatch
  7. Fade a Element
  8. Fade a Element Using CSS Transition
  9. Shake Element
  10. How to Create Tooltip
  11. Falling Snow Effect
  12. JavaScript: Floating Box Following Scroll

DOM Misc

  1. Value of “this” in Event Handler
  2. Event Delegation
  3. Get Current Script Tag
  4. insertAfter Element
  5. Randomize List
  6. create Document Fragment
  7. innerHTML, nodeValue, textContent, innerText?

jQuery

  1. jQuery Basics
  2. jQuery() vs querySelectorAll()
  3. Write JQuery Plugin

node.js