Collision-resistant object keys
Attach metadata or internal state to an object without competing with ordinary string property names.
JavaScript · Class
Symbol
Symbol is a built-in function that creates unique, immutable primitive values. Symbols can serve as non-colliding object property keys, while Symbol.for() provides shared values through the global symbol registry.
- Since
- ES2015
How it works
Symbol is a function-like built-in that creates an immutable primitive with unique identity. Use the resulting value as an object key when a property should not collide with string keys; use Symbol.for and Symbol.keyFor when sharing symbols through the global registry is required.
Syntax
Symbol(description)Parameters
| Name | Type | Description |
|---|---|---|
description | string | Optional text description associated with the symbol; it is used for display and does not determine uniqueness. |
Returns
A new primitive value of type symbol.
Key points
- Use symbols for property keys that should not collide with keys added by unrelated code.
- A symbol key is distinct from every string key and from separately created symbols.
- Call Symbol with an optional string description; the description helps debugging but does not establish identity.
- typeof aSymbol returns "symbol", which identifies the primitive's type.
- Use Object.getOwnPropertySymbols to enumerate an object's own symbol-keyed properties.
- Use Symbol.for to obtain registry symbols and Symbol.keyFor to retrieve their registry keys.
Common mistakes
- Symbol() returns a primitive, not a Symbol wrapper object.
- Do not call Symbol with new; doing so throws a TypeError.
- Calling Symbol repeatedly with the same description still produces different symbols.
- Symbol.for uses registry identity, so it differs from creating a fresh symbol with Symbol().
Example: Use a symbol as an object property key
const secret = Symbol("secret");
const record = { id: 7, [secret]: "internal" };
console.log(record[secret]);
console.log(typeof secret);
console.log(Object.getOwnPropertySymbols(record).length);A symbol creates a unique property key that can be used and later retrieved through the same symbol reference.
When to use it
Language protocol customization
Define protocol hooks recognized by JavaScript features, such as custom iteration behavior.
Cross-module or cross-realm coordination
Share a named symbol between code that uses the global symbol registry.
Interview questions
QWhat does Symbol() create, and are descriptions identity?
Symbol() creates a unique primitive symbol, optionally carrying a description. Each call has distinct identity, even when descriptions match.
Follow-up: How can symbols be shared across realms? Use Symbol.for(key), which retrieves or creates a symbol in the global symbol registry.
QWhy use a Symbol as an object property key?
A symbol can be used as an object property key, reducing accidental collisions with string-named properties. The same symbol reference is needed to access that property directly.
Follow-up: How can symbol-keyed properties be discovered? Object.getOwnPropertySymbols(object) returns an array of the object's own symbol keys.
QCan Symbol be called with new?
Symbol is not constructible with new; attempting new Symbol() throws a TypeError. If an object wrapper is specifically needed, Object(symbol) creates one.
Follow-up: How can the primitive and wrapper be distinguished? typeof the primitive is "symbol", while typeof its wrapper is "object".
Related
Symbol.for()Symbol.keyFor()Object.getOwnPropertySymbols()Symbol.prototype.descriptionSymbol.toPrimitive