Narrowing
IntermediateHow TypeScript follows your checks and early returns through a function, narrowing a union like string | number | null until only one type is left.
Nothing in scope yet
No errors
Spaceplay or pause←→previous or next stepRback to the start
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 TypeErrorfor classes.in:'radius' in shapechecks for a property.- Truthiness:
if (value)removesnullandundefined(and the other falsy values). - Your own guards: a function returning
value is Fishtells TypeScript what atrueresult 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
- 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
- Step 2:
value === nullis a type guard. Inside this if, TypeScript knows value is null.Line 2
- Step 3:
That branch returns, so null can never get past it. After the if, value is string | number.
Lines 3–4
- Step 4:
typeof value === "string"narrows again: in this branch value is a string, so.lengthis allowed.Lines 6–7
- Step 5:
In the else branch, string is ruled out and only number is left, so the number method
toFixedis allowed.Lines 8–9
- Step 6:
After the if/else, both branches meet again, and value is string | number once more.
Line 10
- Step 7:
This check narrows value to number, and the branch returns.
Lines 12–13
- Step 8:
After that early return, number is gone too. On this last line, value can only be a string.
Line 16
- Step 9:
Take the checks away and value would still be string | number | null here. TypeScript would then report two errors.
Line 16
- Step 10:
With them, value is string on this line, so
toUpperCaseis fine and both errors are gone.Line 16
- 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.