Union & Intersection Types

Reviewed & published by Brayan K

A union type (A | B) lets a value be one of several types, while an intersection type (A & B) combines several types into one that has all their members at once.

Part of the free TypeScript course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

What You'll Learn

• Write union types with | to allow a value to be one of several types
• Narrow a union (with typeof and more) before using a value safely
• Use a union of literals as a tidy, enum-like set of options
• Write intersection types with & to combine several shapes into one
• Build discriminated unions with a shared 'kind' field for clean branching
• Decide when 'or' (union) vs 'and' (intersection) is the right tool

💡 Real-World Analogy

Think of a payment method. A union is "pay with cash OR card OR voucher" — at checkout you'll use exactly one of them, so the code must check which one before acting. An intersection is a VIP membership card that is also a payment card — a single object that is both at once, carrying the abilities of both. Union = a choice between alternatives; intersection = a mash-up that has it all.

1. Union Types: One of Several

A union is written with the pipe | and means the value can be any one of the listed types — for example string | number accepts both "ab12" and 42. Because the value might be either, TypeScript only lets you use operations valid for every member until you narrow it. The most common narrowing tool is typeof, which you'll see below.

// A union widens what a value is ALLOWED to be:
type Id = string | number;

function formatId(id: Id): string {
  if (typeof id === "string") {
    return "ID-" + id.toUpperCase();   // id is 'string' here
  }
  return "ID-" + id.toFixed(0).padStart(5, "0"); // id is 'number' here
}

// Union of literal types = a fixed menu of allowed values:
type Status = "active" | "paused" | "closed";
let s: Status = "active";   // ✅
// let bad: Status = "open"; // ❌ '"open"' is not assignable to type 'Status'

// A UNION type (written A | B) means "this value is EITHER an A or a B".
// In TypeScript:  function format(id: string | number) { ... }
// At runtime it's just a normal value — the union lives in the types only.
// We check WHICH kind it is (this is called "narrowing") before using it.

function formatId(id) {
  // Is it a string? Then string methods are safe.
  if (typeof id === "string") {
    return "ID-" + id.toUpperCase();
  }
  // Otherwise it's a number here — number behaviour is safe.
  return "ID-" + id.toFixed(0).padStart(5, "0");
}

console.log(formatId("ab12"));  // ID-AB12
console.log(formatId(42));      // ID-00042

// A union of literal strings makes a tidy fixed set of options:
//   type Status = "active" | "paused" | "closed";
function describe(status) {
  return "The account is currently " + status + ".";
}
console.log(describe("active")); // The account is currently active.
console.log(describe("paused")); // The account is currently paused.

// In a .ts file the signatures would be:
//   function formatId(id: string | number): string { ... }
//   type Status = "active" | "paused" | "closed";

2. Intersection Types: All at Once

An intersection is written with the ampersand & and combines shapes: Person & Employee describes an object that has every property of Person and every property of Employee. It's the natural way to express "this thing is both a person and an employee", and at runtime you simply build one object carrying all the fields.

type Person   = { name: string; age: number };
type Employee = { employeeId: string; department: string };

// '&' MERGES the two shapes — Staff must have all four properties:
type Staff = Person & Employee;

const staff: Staff = {
  name: "Ada",
  age: 36,
  employeeId: "E-77",
  department: "Engineering",
};

// Missing even one property is an error:
// const bad: Staff = { name: "Ada", age: 36 };
// ❌ Property 'employeeId' is missing in type ... but required in type 'Staff'

// An INTERSECTION type (written A & B) means "this value has EVERYTHING
// from A AND EVERYTHING from B at the same time". It COMBINES shapes.
// In TypeScript:  type Staff = Person & Employee;
// At runtime that's simply one object holding all the properties.

const person = { name: "Ada", age: 36 };
const employee = { employeeId: "E-77", department: "Engineering" };

// Build a value that satisfies BOTH shapes by merging them:
const staff = { ...person, ...employee };

console.log(staff.name);        // Ada        (from Person)
console.log(staff.age);         // 36         (from Person)
console.log(staff.employeeId);  // E-77       (from Employee)
console.log(staff.department);  // Engineering(from Employee)

// A function that needs BOTH sets of fields can read any of them safely:
function badge(s) {
  return s.name + " (" + s.employeeId + ", " + s.department + ")";
}
console.log(badge(staff)); // Ada (E-77, Engineering)

// In a .ts file:
//   type Person   = { name: string; age: number };
//   type Employee = { employeeId: string; department: string };
//   type Staff    = Person & Employee;        // has ALL four fields

3. Discriminated Unions: The Best of Both

The most powerful pattern combines unions with a shared literal field. Give each member a common tag — often called kind or type — and a switch on that tag lets TypeScript narrow to the exact member in each branch. This discriminated union is how you model "one of several shapes" cleanly and safely.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle": return Math.PI * shape.radius ** 2; // 'radius' is known here
    case "rect":   return shape.width * shape.height;  // 'width'/'height' known here
  }
}

// The MOST useful union pattern: a "discriminated union".
// Each member shares a common literal field (the "discriminant", here 'kind')
// that tells you exactly which member you have, so narrowing is clean.

// In TypeScript:
//   type Shape =
//     | { kind: "circle"; radius: number }
//     | { kind: "rect"; width: number; height: number };

function area(shape) {
  switch (shape.kind) {
    case "circle":
      // Here TypeScript KNOWS shape has 'radius'
      return Math.PI * shape.radius * shape.radius;
    case "rect":
      // Here it KNOWS shape has 'width' and 'height'
      return shape.width * shape.height;
    default:
      return 0;
  }
}

console.log(area({ kind: "circle", radius: 2 }).toFixed(2)); // 12.57
console.log(area({ kind: "rect", width: 3, height: 4 }));     // 12

// Checking the 'kind' field is what lets each branch use the right fields.

🎯 Your Turn

Here's a classic union job: a function that accepts either a single string or an array of strings and always returns an array. Fill in the two blanks marked ___, then run it.

// 🎯 YOUR TURN — replace each ___ then press "Try it Yourself".
// We're modelling a value that is EITHER a string OR a string[].

function toList(value) {
  // 1) If it is a single string, wrap it in an array:
  if (typeof value === ___) {   // 👉 the string "string"
    return [value];
  }
  // 2) Otherwise assume it's already an array and return it as-is:
  return ___;                   // 👉 just return value
}

console.log(toList("apple"));            // [ 'apple' ]
console.log(toList(["a", "b", "c"]));    // [ 'a', 'b', 'c' ]

// ✅ Expected output:
//    [ 'apple' ]
//    [ 'a', 'b', 'c' ]

Common Errors (and the fix)

• ❌ "Property 'toUpperCase' does not exist on type 'string | number'" — you tried to use a string-only method on a union. ✅ Narrow first: if (typeof id === "string") { id.toUpperCase() }.
• ❌ "Property 'employeeId' is missing in type ... but required in type 'Staff'" — an intersection needs every property from both shapes. ✅ Add the missing fields so the object satisfies both sides of the &.
• ❌ Forgetting the discriminant — without a shared kind field, TypeScript can't tell members apart and blocks access to unique properties. ✅ Add a literal tag (kind: "circle") to each member and switch on it.
• ❌ Confusing | and & — writing Person | Employee when you meant "has both" gives a value where only the shared properties are safe. ✅ Use & to combine, | to offer a choice.

Pro Tips

• 💡 Reach for a discriminated union whenever a value is "one of several shapes" — API responses, UI states (loading/loaded/error), and events all fit perfectly.
• 💡 Unions of string literals ("sm" | "md" | "lg") make a lightweight, type-safe set of options without needing an enum.
• 💡 Intersections shine with mixins — combine small capability types (Timestamped & Identifiable) into richer ones.
• 💡 Add a default branch in your switch over a union; later, an assertNever(x) there catches any member you forgot to handle.

Mini-Challenge: Payment Result

No blanks this time — just a brief and a starting outline. Build the discriminated union handler yourself, run it, and check your output against the example in the comments.

// 🎯 MINI-CHALLENGE: a payment "result" discriminated union
// Model the OUTCOME of a payment with two shapes that share a 'status' field:
//   { status: "ok",   amount: number }
//   { status: "error", message: string }
//
// 1. Write describePayment(result) that switches on result.status.
// 2. For "ok"    return  "Paid £<amount>"
// 3. For "error" return  "Failed: <message>"
// 4. Call it with one of each and log the results.
//
// ✅ Expected output:
//    Paid £19.99
//    Failed: Card declined

// your code here

🎉 Lesson Complete

• ✅ A union A | B lets a value be one of several types — narrow it before use
• ✅ typeof narrowing refines a union to a single type inside each branch
• ✅ A union of literals ("a" | "b" | "c") is a tidy set of allowed options
• ✅ An intersection A & B combines shapes — the value has all members at once
• ✅ A discriminated union uses a shared kind field for clean, safe branching

Practice quiz

Continue this course

• Previous: Advanced Types
• Next: Literal Types & const Assertions — Exact string/number types and locking values with as const
• Quick reference: TypeScript cheat sheet › Basic Types

Frequently asked questions

When do I use a union (|) vs an intersection (&)?

Use a union (A | B) when a value can be one of several alternatives — it is EITHER an A OR a B. Use an intersection (A & B) when a value must satisfy several shapes at once — it has EVERYTHING from A AND from B. A rule of thumb: 'or' problems are unions, 'and' problems are intersections.

Why does TypeScript stop me using a method on a union value?

Because the method might not exist on every member of the union. If a value is string | number, you cannot call .toUpperCase() directly — it only exists on string. You must narrow first (e.g. with typeof) so TypeScript can prove which member you have in that branch.

What is a discriminated (tagged) union?

It is a union where every member shares one common literal field — the discriminant, often called kind, type, or status. Switching on that field lets TypeScript narrow to the exact member in each branch, so you can safely use that member's unique properties. It is the cleanest way to model 'one of several shapes'.

What happens if I intersect two types that conflict?

If two members of an intersection require the same property with incompatible types (e.g. { x: string } & { x: number }), that property's type becomes never — no value can satisfy both — so it effectively becomes impossible to construct. Intersections work best on shapes with non-overlapping properties.

Related lessons

• Basic Types