PricingLoginStart free
TypeScript Academy · Lesson

Distributive Conditional Types

Understand how conditionals distribute over union members.

Lesson 4 of 413 steps

Distributive Conditional Types is a free TypeScript Academy lesson on CoddyKit. This is lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the TypeScript Academy learning path, and your progress syncs across the web and the CoddyKit app. The TypeScript Academy course includes 4 lessons in total.

Welcome

Distributive conditional types apply a conditional type to each member of a union separately. This powerful behavior enables union transformation and filtering.

What Is Distribution

When a conditional type has a bare generic T and T is a union, TypeScript applies the conditional to each union member separately.
type Wrap<T> = T extends any ? { value: T } : never;
type R = Wrap<string | number>;
// = { value: string } | { value: number }

The Key Condition

Distribution only occurs when T is a bare (not wrapped) generic type parameter. Wrapping T in a tuple prevents it.
type Bare<T> = T extends string ? 'yes' : 'no';
type Wrapped<T> = [T] extends [string] ? 'yes' : 'no';
type B = Bare<'a' | 'b'>; // 'yes' | 'yes' = 'yes'
type W = Wrapped<'a' | 'b'>; // 'no' — treated as a tuple

Filtering Unions with never

Returning never from the false branch filters out union members.
type StringsOnly<T> = T extends string ? T : never;
type S = StringsOnly<string | number | boolean>; // string

Extract Built-In

Extract is implemented with a distributive conditional that keeps members assignable to U.
type Extract<T, U> = T extends U ? T : never;
type E = Extract<string | number | boolean, string | number>; // string | number

Exclude Built-In

Exclude removes union members assignable to U.
type Exclude<T, U> = T extends U ? never : T;
type Ex = Exclude<string | number | boolean, boolean>; // string | number

ToArray Distribution

Apply ToArray to each union member separately via distribution.
type ToArray<T> = T extends any ? T[] : never;
type R = ToArray<string | number>; // string[] | number[]

Preventing Distribution Use Case

Sometimes you want to treat the whole union as a single type argument, not distribute over it.
type IsUnion<T> = [T] extends [T] ? [T] extends [Exclude<T, T>] ? false : true : false;

Distributive Mapped Types

Combine distributive conditionals with mapped types to transform selective properties.
type PickByValue<T, V> = {
  [K in keyof T as T[K] extends V ? K : never]: T[K]
};

Distributive Conditional in ReturnType

The distributive behavior makes ReturnType work correctly when T is a union of function types.
type Fn = (() => string) | (() => number);
type R = ReturnType<Fn>; // string | number

Eager vs Lazy Distribution

TypeScript defers (doesn't evaluate) conditional types with free type parameters until they are resolved — this is lazy evaluation.

Quick Check

What is `type R = (string | number) extends string ? 'yes' : 'no'` when T is NOT a bare generic?
Answer it in the interactive lesson

Recap

Distributive conditional types apply to each union member separately when T is a bare generic parameter. This powers Extract, Exclude, and custom union filtering. Wrap in a tuple to prevent distribution.
Free to start

Learn TypeScript with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses
101
Lessons
352
Start learning freeView the full course

Frequently Asked Questions

Is the “Distributive Conditional Types” lesson free?

Yes — the full text of “Distributive Conditional Types” is free to read here on the web. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the TypeScript Academy course, upgrade to CoddyKit PRO. The TypeScript Academy course includes 4 lessons in total.

What will I learn in “Distributive Conditional Types”?

Understand how conditionals distribute over union members. You practise TypeScript Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start TypeScript Academy?

No prior experience is required. TypeScript Academy on CoddyKit is structured for beginners through advanced learners, so you can start here or from the beginning and move at your own pace. This is lesson 4 of 4.

How long does the “Distributive Conditional Types” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this TypeScript Academy lesson?

Yes. Every TypeScript Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. keyof and Indexed Access Types
  2. Generic Constraints: Narrowing Type Parameters
  3. Conditional Types: T extends U ? X : Y
  4. Distributive Conditional Types
← Back to TypeScript Academy