Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Narrowing and Type Guards

Discriminated union narrowing in TypeScript

Reference for discriminant narrowing in TypeScript: tagged unions, literal tag fields, switch and if checks, destructuring, optional tags and common mistakes.

A discriminated union is a union of object types that all share one property, the discriminant, whose type is a different literal in each member. Checking that property tells TypeScript which member you hold, and every other property of that member becomes available.

This pattern models results, events, actions and states: each variant carries only the fields that make sense for it, and the compiler stops you from reading a field in the wrong variant.

TypeScript
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number };

Try it

TypeScript A tagged union with switch

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 Result type with if and destructuring

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 Reading a field from the wrong variant

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
type U = { tag: "a"; a: A } | { tag: "b"; b: B };

if (u.tag === "a") { /* u: { tag: "a"; a: A } */ }
switch (u.tag) { case "a": ...; case "b": ... }
Requirement Description
Shared property Every member declares the same property name.
Literal types The property's type in each member is a unit type: a string, number, boolean, null, undefined or enum member literal.
Distinct values No two members use the same literal (otherwise they cannot be told apart).

Edge cases:

  • A tag that is typed as plain string is not a discriminant; the narrowing needs literals.
  • Accessing a property that exists only in some members is error TS2339 ("Property 'x' does not exist on type ...").
  • A tag with null or undefined as one of its values works too ({ error: null; data: T } | { error: Error; data: null }).

Usage notes

  • Pick a stable name. kind, type, tag and status are common. Use the same one across a codebase so tools and readers recognize it.
  • Combine with exhaustiveness. Add a default that assigns the value to never, so a new variant causes a compile error. See exhaustiveness checking.
  • Destructuring. Since TypeScript 4.6, destructuring a discriminated union into separate const variables keeps them linked: checking kind narrows the sibling variables. This works for parameters destructured in the signature too, when none are reassigned.
  • Optional discriminants such as kind?: "a" are allowed, with undefined as one of the values.
  • Data from outside. JSON from a network gives you unknown. The union describes shape only after you validate it. See user-defined guards.
  • Prefer over optional fields. A single type with many optional properties cannot express "if kind is circle then radius is present". A union can.
  • Runtime cost. None: the tag is ordinary data you store anyway.