Suggest an edit

Improve this article

Refine the answer for “What does the symbol type do?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

### What the `symbol` type does in TypeScript

The `symbol` type represents a **unique and immutable value**,
which is often used as an **identifier (key)** for object properties.

It was added in **ES2015 (ES6)** and has been supported by TypeScript from the start.

---

### The essence of `symbol`

Every time you create a `Symbol()`, it generates a **unique value**, even if you pass the same description (the description is just a label for debugging).

```javascript
const id1 = Symbol("user");
const id2 = Symbol("user");

console.log(id1 === id2); // false - symbols are unique!
```

So even with the same name `"user"`, these are **different symbols**.

---

### How to declare a variable of type `symbol`

#### 1. Implicitly (TS infers the type itself):

```javascript
const token = Symbol("auth"); // type: symbol
```

#### 2. Explicitly specifying the type:

```javascript
let key: symbol = Symbol("key");
```

---

### Symbols as object keys

`symbol` is often used to add a **unique property** to an object,
one that will not be accidentally overwritten or shown during iteration.

```javascript
const ID = Symbol("id");

const user = {
  name: "Tim",
  [ID]: 12345,
};

console.log(user.name);  // "Tim"
console.log(user[ID]);   // 12345
```

> Properties keyed by a symbol are **not visible** when iterating via `for...in` or `Object.keys()`:
>
> ```javascript
> console.log(Object.keys(user)); // ["name"]
> ```

---

### Why `symbol` is needed

1. **To protect data** - unique properties that cannot be accidentally overwritten.
2. **To create "hidden" keys** in libraries, so they don't collide with other properties.
3. **To describe unique constants**, especially in enum-like structures.
4. **For metaprogramming** - used in special "well-known symbols".

---

### "Well-known symbols"

JavaScript has a set of built-in symbols that let you change the standard behavior of objects:

| Symbol | Purpose |
|---|---|
| `Symbol.iterator` | Defines iteration of an object (`for...of`) |
| `Symbol.toStringTag` | Defines what `Object.prototype.toString()` returns |
| `Symbol.hasInstance` | Defines the behavior of `instanceof` |
| `Symbol.toPrimitive` | Controls conversion of an object to a primitive |
| `Symbol.asyncIterator` | For asynchronous iterators |
| `Symbol.match`, `Symbol.replace`, `Symbol.search`, `Symbol.split` | Let you customize work with strings and RegExp |

Example:

```javascript
const person = {
  [Symbol.toPrimitive](hint) {
    if (hint === "number") return 42;
    return "Tim";
  }
};

console.log(+person); // 42
console.log(`${person}`); // "Tim"
```

---

### Features and limitations

1. Symbols cannot be automatically converted to a string:

```javascript
  const s = Symbol("id");
  console.log("ID: " + s); // TypeError
  console.log(s.toString()); // "Symbol(id)"
  ```
2. Symbols are **unique**, but you can get **shared (global)** ones via `Symbol.for()`:

```javascript
  const a = Symbol.for("shared");
  const b = Symbol.for("shared");
  console.log(a === b); // true - the same global symbol
  ```

---

### Summary

| Property | Description |
|---|---|
| Type | Primitive |
| Created via | `Symbol()` or `Symbol.for()` |
| Uniqueness | Always unique (except global ones via `Symbol.for`) |
| Main use | Unique object keys, safe identifiers |
| Conversion to string | Only manually via `.toString()` |
| Access to value | Only via `[symbol]`, not via dot notation |

Markdown · drag & drop images · ⌘B / ⌘I shortcuts509 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.