Skip to content

Type Narrowing in TypeScript

How TypeScript refines union types inside conditional branches using type guards.

What you'll learn

  • What type narrowing is and why it is essential for unions
  • Narrowing with typeof, instanceof, and the in operator
  • Discriminated unions for reliable narrowing
  • How control flow analysis tracks narrowed types

Concept

The Need for Narrowing

When a variable has a union type like string | number, you cannot call string-specific methods on it — the compiler does not know which type is in play. Narrowing is the process of refining the type within a conditional branch so the compiler knows the exact type. After a narrowing check, TypeScript gives you the narrowed type inside that branch, letting you access type-specific properties safely.

Narrowing Techniques

The three main narrowing tools are: typeof for primitives (typeof x === "string"), instanceof for classes (x instanceof Date), and the in operator for object property presence ("name" in obj). Each tells the compiler which branch of a union applies. TypeScript also narrows on truthiness checks, equality comparisons (x === null), and custom type guard functions (covered in the next lesson).

Discriminated Unions

A discriminated union is a union where every member has a common property with a unique literal value — the discriminant. For example, type Event = { type: "click"; x: number } | { type: "scroll"; y: number }. The type property discriminates the union. In a switch on event.type, TypeScript narrows to the exact member in each case. This pattern is the most reliable narrowing strategy for complex unions.

Example

              // typeof narrowing for primitives.
function pad(value: string | number): string {
  if (typeof value === "number") {
    // Here, value is narrowed to number.
    return value.toFixed(2);
  }
  // Here, value is narrowed to string.
  return value.padStart(10, " ");
}

// Discriminated union — 'type' is the discriminant.
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; size: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      // Narrowed to the circle variant.
      return Math.PI * shape.radius ** 2;
    case "square":
      // Narrowed to the square variant.
      return shape.size ** 2;
  }
}

console.log(pad(42), pad("hi"));
console.log(area({ kind: "circle", radius: 5 }));
console.log(area({ kind: "square", size: 4 }));
            

Narrowing refines a union type inside branches. typeof handles primitives, instanceof handles classes, in checks property presence. Discriminated unions with a common literal field are the most robust pattern.

Try it

  • JSON to TypeScript

    Polymorphic API responses often produce discriminated unions.

  • Code Diff

    Compare narrowed and non-narrowed code to see the safety difference.

Common mistakes

The mistake

Accessing union-specific properties without narrowing first

The fix

The compiler only allows type-specific access after a narrowing check. Use typeof, instanceof, in, or a discriminant switch to narrow before accessing.

The mistake

Forgetting that narrowing does not persist outside the branch

The fix

Narrowing applies only within the conditional block. After the if/else, the type reverts to the full union. Re-narrow or extract the narrowed logic into a helper.

Practice Type Narrowing in TypeScript

11 exercises

Practice Type Narrowing in TypeScript

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors