Skip to content
YouTurkey Tech
All TypeScript topics

Narrowing

Intermediate

How TypeScript follows your checks and early returns through a function, narrowing a union like string | number | null until only one type is left.

Types in scope

Nothing in scope yet

Errors

No errors

0/11Press Play, or step through with the arrows, to begin.
Step 0 of 11

Explanation

3 min read

On this page

What is narrowing in TypeScript?

A union type like string | number | null says a value can be any one of several types. That is honest but limiting: TypeScript only lets you use what every member has in common, so value.toUpperCase() is an error until you prove value is a string.

Narrowing is how you prove it. When you check a value, TypeScript works out which members of the union can still reach each line, and gives the value that smaller, narrowed type there.

How does TypeScript narrow a type?

It reads your code the way it runs, a process called , and recognizes checks called type guards:

  • Equality: value === null, value !== undefined, shape.kind === 'circle'.
  • typeof: typeof value === 'string' for primitives (string, number, boolean, bigint, symbol, undefined, function, object).
  • instanceof: error instanceof TypeError for classes.
  • in: 'radius' in shape checks for a property.
  • Truthiness: if (value) removes null and undefined (and the other falsy values).
  • Your own guards: a function returning value is Fish tells TypeScript what a true result means.

Branches matter too. Inside an if, the type is narrowed; in the else, the checked members are removed. After a branch that always returns or throws, what it handled can no longer appear, so early returns narrow the rest of the function. Where branches meet again, the types join back into a union.

What mistakes do people make with narrowing?

Mini example

A discriminated union gives every member a shared literal property, here kind. Checking it narrows to exactly one member, and TypeScript also knows the switch covers every case:

type Shape = { kind: 'circle'; radius: number } | { kind: 'square'; side: number }; function area(shape: Shape): number {  switch (shape.kind) {    case 'circle':      return Math.PI * shape.radius ** 2; // shape: the circle member    case 'square':      return shape.side ** 2; // shape: the square member  }}

Quick check

Inside case "circle": of the mini example, what is the type of shape?

Further reading

All steps as text
  1. Step 1:

    value is declared as a union: string | number | null. Until you check, you can only use what all three have in common.

    Line 1

  2. Step 2:

    value === null is a type guard. Inside this if, TypeScript knows value is null.

    Line 2

  3. Step 3:

    That branch returns, so null can never get past it. After the if, value is string | number.

    Lines 3–4

  4. Step 4:

    typeof value === "string" narrows again: in this branch value is a string, so .length is allowed.

    Lines 6–7

  5. Step 5:

    In the else branch, string is ruled out and only number is left, so the number method toFixed is allowed.

    Lines 8–9

  6. Step 6:

    After the if/else, both branches meet again, and value is string | number once more.

    Line 10

  7. Step 7:

    This check narrows value to number, and the branch returns.

    Lines 12–13

  8. Step 8:

    After that early return, number is gone too. On this last line, value can only be a string.

    Line 16

  9. Step 9:

    Take the checks away and value would still be string | number | null here. TypeScript would then report two errors.

    Line 16

  10. Step 10:

    With them, value is string on this line, so toUpperCase is fine and both errors are gone.

    Line 16

  11. Step 11:

    TypeScript follows your code: every check and every early return narrows the union, and only the types left decide what you may do.