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.
type Shape = | { kind: "circle"; radius: number } | { kind: "square"; side: number };
Try it
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.
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.
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
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
stringis 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
nullorundefinedas one of its values works too ({ error: null; data: T } | { error: Error; data: null }).
Usage notes
- Pick a stable name.
kind,type,tagandstatusare common. Use the same one across a codebase so tools and readers recognize it. - Combine with exhaustiveness. Add a
defaultthat assigns the value tonever, so a new variant causes a compile error. See exhaustiveness checking. - Destructuring. Since TypeScript 4.6, destructuring a discriminated union into separate
constvariables keeps them linked: checkingkindnarrows the sibling variables. This works for parameters destructured in the signature too, when none are reassigned. - Optional discriminants such as
kind?: "a"are allowed, withundefinedas 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
kindiscirclethenradiusis present". A union can. - Runtime cost. None: the tag is ordinary data you store anyway.