Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Narrowing and Type Guards

switch (true) narrowing in TypeScript

Reference for switch (true) in TypeScript 5.3 and later: how boolean case expressions narrow the switched value, fall-through, and when if chains are better.

switch (true) is a JavaScript idiom where each case holds a boolean expression instead of a constant. The first case whose expression is true runs. It reads like a flat chain of if / else if branches.

TypeScript 5.3 taught the compiler to narrow in this form. Each case expression is treated like an if condition, so inside the clause the variables it tests are narrowed, and later clauses see the leftover types.

TypeScript
function f(x: string | number | boolean) {
  switch (true) {
    case typeof x === "string":
      return x.length;   // string
    case typeof x === "number":
      return x.toFixed(); // number
    default:
      return x;          // boolean
  }
}

Try it

TypeScript Narrowing with several kinds of checks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Ranges plus narrowing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Fall-through keeps the union

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
switch (true) {
  case condition1:
    ...
    break;
  case condition2:
    ...
    break;
  default:
    ...
}
Part Description
switch (true) The switched value is the literal true.
case condition: Runs when condition === true (strict equality, so the value must be exactly the boolean true, not just truthy).
default: Runs when no condition was true; types narrowed by the failed conditions apply.

Edge cases:

  • A case value that is truthy but not true (such as "yes" or 1) never matches at run time. Use real booleans, with !! if needed.
  • If you fall through from a case with narrowing into the next one, the types from both are combined.
  • Cases are tested top to bottom, and conditions with side effects run in that order.

Usage notes

  • Version note. Narrowing in switch (true) arrived in TypeScript 5.3. Earlier versions evaluate the code correctly but do not narrow.
  • When to use it. It is tidy when you have many mutually exclusive tests on different aspects of a value. For a tag field, a plain switch (x.kind) is shorter and narrows in every version (see discriminant narrowing).
  • No exhaustiveness. The compiler does not know the conditions cover the type, so a default that expects never will not compile unless all cases really narrow away every member. Normal exhaustiveness checks are in exhaustiveness checking.
  • Case expressions are checked on their own. The test written in a later case is not narrowed by the failed tests above it (writing case score >= 90 after case score === undefined reports TS18048, as it did while preparing the second example). Repeat the check inside the expression, as that example does.
  • Equals if / else if. Each clause behaves like else if (condition). Pick the form your team reads more easily.
  • Linting. Some style guides discourage switch (true). It is valid JavaScript and common in TypeScript code that mixes ranges and guards.
  • Combining with predicates. Case expressions can call type guard functions and the narrowing follows.