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

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...inloop.
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.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





