Suggest an edit

Improve this article

Refine the answer for “What does the unknown type mean?”. 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 `unknown` type means in TypeScript

The `unknown` type is a **safe alternative** to `any`.
It means:

> "The type of the value is **not known in advance**, and before using it
> you need to **check the type** (type narrowing)."

In other words, `unknown` tells TypeScript:

> "I don't know what this value is, but I want to work with it safely."

---

### Basic usage example

```javascript
let value: unknown;

value = 42;
value = "Hello";
value = { name: "Tim" };
value = true;
```

So you can assign `unknown` **any value**,
but **you cannot use it without checking**.

---

### How it differs from `any`

| Operation | `any` | `unknown` |
| --- | --- | --- |
| Can assign any values | yes | yes |
| Can perform any operations | yes | no (type must be checked) |
| Type safety | no | yes |
| Needs narrowing before use | no | yes |

Example:

```javascript
let a: any = 10;
a.toUpperCase(); // the error will only appear at runtime

let b: unknown = 10;
// b.toUpperCase(); // compile-time error - TypeScript does not know this is a string
```

To use `unknown`, you must **first check the type**:

```javascript
if (typeof b === "string") {
  console.log(b.toUpperCase()); // now it's fine
}
```

---

### Examples of using `unknown`

#### 1. When working with external data (for example, an API)

```javascript
function parseJSON(input: string): unknown {
  return JSON.parse(input);
}

#### 2. With dynamic data types

```javascript
function handleInput(data: unknown) {
  if (typeof data === "number") {
    console.log(data.toFixed(2));
  } else if (typeof data === "string") {
    console.log(data.toUpperCase());
  } else {
    console.log("Unknown type");
  }
}
```

---

### Features of the `unknown` type

1. `unknown` **is a supertype of all types**,
meaning **anything** can be assigned to it:

```javascript
  let x: unknown;
  x = 123;
  x = "string";
  x = true;
  ```
2. But the reverse is not true - you cannot assign `unknown` to a variable of another type without a check:

```javascript
  let y: number;
  let x: unknown = 10;

// y = x; // error - the type must be explicitly narrowed or cast
  y = x as number; // correct
  ```
3. The `unknown` type is the **"top" type of TypeScript's type system**
(an analog of `any`, but safe):

```javascript
  never ⊂ string ⊂ unknown
  ```

---

### Example: comparing `unknown` and `any`

```javascript
function testAny(value: any) {
  value.foo.bar(); // compiles, but blows up at runtime
}

function testUnknown(value: unknown) {
  // value.foo.bar(); // compile-time error - safe
  if (typeof value === "object" && value !== null) {
    console.log("Object:", value);
  }
}
```

---

### Quick summary

| Property | Description |
| --- | --- |
| Type | Primitive utility type |
| Purpose | Safe analog of `any` |
| Can be assigned | Any value |
| Can be used | Only after a type check |
| Typing | Strict and safe |
| Where it's used | Unknown data (API, `JSON.parse`, user input) |

---

### Summary

- `any` → "Do whatever you want, TypeScript doesn't check."
- `unknown` → "You can store anything, **but prove** it's safe."

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

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.