Union and Intersection Types
Combine types with unions (A | B) and intersections (A & B) for flexible type modeling.
What you'll learn
- How union types (A | B) let a value be one of several types
- How intersection types (A & B) combine multiple types into one
- Using string literal unions for enums-like patterns
- Narrowing union types with type guards
Concept
Union Types
A union type (A | B) means a value can be either type A or type B. For example, type ID = number | string allows an ID that is either a number or a string. Union types are extremely common for function parameters that accept multiple input shapes, return types that can be different things, and string literal unions like type Direction = "left" | "right" | "up" | "down" which act as a lightweight enum.
Intersection Types
An intersection type (A & B) combines all properties of A and B into a single type — a value must satisfy both. For example, type Admin = User & { permissions: string[] } has all properties of User plus permissions. Intersections are the type-alias equivalent of interface extends. They are useful for composing types from smaller pieces, especially when combining types from different sources.
Narrowing Unions
When you have a union type, TypeScript needs to know which specific type is in play before you can access type-specific properties. This is called narrowing. You narrow with type guards: typeof checks for primitives, in operator for property presence, and instanceof for classes. The compiler tracks these checks and gives you the narrowed type inside each branch.
Example
// Union — a value can be one of several types.
type ID = number | string;
function formatId(id: ID): string {
return String(id);
}
// String literal union — acts like a lightweight enum.
type Direction = "left" | "right" | "up" | "down";
function move(dir: Direction): void {
console.log("Moving", dir);
}
// Intersection — combines all properties from both types.
type Timestamps = { createdAt: Date; updatedAt: Date };
type User = { id: number; name: string };
type UserRecord = User & Timestamps;
const record: UserRecord = {
id: 1,
name: "Alice",
createdAt: new Date(),
updatedAt: new Date(),
};
move("left");
console.log(formatId(42), formatId("abc"));
Unions (|) allow one of several types. Intersections (&) require all properties from every type. String literal unions are a lightweight alternative to enums.
Try it
- JSON to TypeScript
API responses often produce union types for optional or polymorphic fields.
- JSON Schema Validator
Validate data shapes that match your union and intersection types.
Common mistakes
The mistake
Accessing properties that only exist on one side of a union without narrowing
The fix
Use a type guard (typeof, in, instanceof) to narrow the union first. The compiler then lets you access the type-specific properties inside that branch.
The mistake
Creating intersections of incompatible types that result in never
The fix
If two types have conflicting property types (e.g. string vs number for the same key), their intersection becomes never. Check for property name conflicts.
Practice Union and Intersection Types
9 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.