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
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.