Basics

What is a Symbol in JavaScript — and why JSON.stringify can't see it

Illustration: a row of ordinary keys and one see-through key that doesn't make it into the box

Put a field with a symbol key into an object and send it to the server:

const id = Symbol('id')
const user = { name: 'Anna', [id]: 42 }

JSON.stringify(user)   // '{"name":"Anna"}'
Object.keys(user)      // ['name']

The field is there — user[id] returns 42. But JSON doesn't see it. Neither does Object.keys. That's not a bug. It's exactly why symbols were invented. Let's figure out what they are and where you've already met them without knowing.

What a Symbol is, in plain words

A Symbol is a value that is guaranteed to be unique. Every call to Symbol() makes a new one, unlike anything else:

Symbol('id') === Symbol('id')   // false

The text in the parentheses is just a debugging label. It doesn't make two symbols equal. Two tags that say "basement key" don't turn two different keys into one.

The main use is a property key on an object. A normal key is a string. Any code can accidentally write user.id and overwrite your field. A symbol key can't be overwritten like that. Only code that holds the symbol itself can reach it.

One more detail: typeof Symbol() returns 'symbol'. It's its own primitive type, like a string or a number. And new Symbol() won't work — you'll get a TypeError.

Why JSON and Object.keys can't see it

Symbol keys are hidden from ordinary iteration. They're skipped by:

  • JSON.stringify — the field simply vanishes from the result;
  • Object.keys, Object.values, Object.entries;
  • the for...in loop.

They're not gone, though. Special methods still find them:

Object.getOwnPropertySymbols(user)   // [Symbol(id)]
Reflect.ownKeys(user)                // ['name', Symbol(id)]

And one trap going the other way. Spread ...user and Object.assign do copy symbol keys. Copy the object — the internal field comes along. Send it over the network — it falls off.

Hence a practical rule. A symbol is great for an internal tag that must not leak into JSON. It's a bad fit for data you save or send — that data will silently disappear. More on how keys work in the article on objects.

The error everyone trips over

A symbol can't turn itself into a string:

'User ' + id    // TypeError: Cannot convert a Symbol value to a string
`key: ${id}`    // same error

A number concatenates. null concatenates. Even an object concatenates into [object Object]. A symbol doesn't — it throws right away. That's deliberate: so a unique key can't quietly become an ordinary string and lose its uniqueness.

If you just need to display it, there are two honest ways:

String(id)        // 'Symbol(id)'
id.description    // 'id'

See Cannot convert a Symbol value to a string in the log? Look for a place where a value gets glued to text. Often it's console.log('...' + key) inside a loop over Reflect.ownKeys.

Where you already use symbols

Here's the unexpected part. You work with symbols every day — just the built-in ones.

for...of. Why can you loop over an array with for...of but not over a plain object? The array has a method under the Symbol.iterator key. The loop looks for exactly that. A plain object doesn't have it, hence TypeError: obj is not iterable. More on loops themselves in the article on loops.

React and forgery protection. Every React element has an internal $$typeof field. It holds a symbol: Symbol.for('react.element'), and in React 19 — Symbol.for('react.transitional.element'). Why? JSON can't store symbols. So an object that arrived from the server as JSON can't pretend to be a React element. If an attacker slips a "ready-made element" into the data, React simply won't render it.

Other "well-known" symbols. Symbol.asyncIterator powers for await — that's how you read streaming responses from AI models. Symbol.toPrimitive decides what an object becomes in +obj. And Symbol.toStringTag is behind the label in [object Map].

Symbol() or Symbol.for()

Sometimes uniqueness gets in the way. Say one module sets a tag, and another — from a different library or an iframe — has to recognize it. That's what the global registry is for:

Symbol.for('app.id') === Symbol.for('app.id')   // true

Symbol.for looks a symbol up by name. If there isn't one, it creates and remembers it. That's how React recognizes its elements even with two copies of the library on the page.

A short rule:

  • need a tag nobody can repeat — Symbol('…');
  • need a tag different parts of the code agree on — Symbol.for('…'), and give it a prefix, like 'myapp.id'.

Does a beginner need to write their own symbols?

Usually not. In a typical app string keys are enough. But understanding symbols pays off: they explain for...of, $$typeof in React and odd errors when concatenating strings.

Why did my symbol field disappear after saving?

Because JSON.stringify skips symbol keys. Same with localStorage, fetch with a JSON body, and any database that goes through JSON. Keep such data under a string key.

How is a symbol different from a string key?

Any code can write the string 'id' and accidentally overwrite the field. A symbol exists as a single instance. The field can only be reached through it, and it doesn't show up in ordinary iteration.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →