Course contentsShow
← TypeScript
Lesson 780 of 1,79618. Conditional TypesFree lesson

Distributive Behavior with Union Types

See how `T extends U ? X : Y` distributes when T is a union, applying the condition to each member separately.

Distributive Behavior with Union Types

What you'll learn: How conditional types automatically distribute over union members, applying the condition to each member separately instead of the whole union at once.


When you pass a union type to a conditional type like T extends U ? X : Y, TypeScript does something special: it distributes the conditional over each member of the union individually.

Think of it like a mail sorting machine. Instead of checking if the entire bag of mail meets a condition, it opens the bag, checks each letter individually, and sorts them one by one. Then it combines the results.

How It Works

type ToArray<T> = T extends any ? T[] : never;

// When T is a union:
type Result = ToArray<string | number>;
// TypeScript distributes this as:
// (string extends any ? string[] : never) | (number extends any ? number[] : never)
// Result: string[] | number[]

Without distribution, you might expect (string | number)[], but distribution gives you string[] | number[] — a union of separate arrays.

Filtering Union Members

type ExtractStrings<T> = T extends string ? T : never;

type OnlyStrings = ExtractStrings<string | number | boolean>;
// Distributes to:
// (string extends string ? string : never) | 
// (number extends string ? never : never) | 
// (boolean extends string ? never : never)
// Result: string

The never results disappear from the union, effectively filtering it.

Real-World Pattern

type Nullable<T> = T extends any ? T | null : never;

type MaybeNull = Nullable<string | number>;
// Result: string | null | number | null
// Which simplifies to: string | number | null

Each union member gets | null added to it separately.

Key Takeaway: When a union type is passed as a type parameter to a conditional type, TypeScript distributes the condition across each member individually, evaluating them separately and combining the results into a new union.