TypeScript Conditional Types and infer, with Examples

A conditional type chooses between two types with a test that reads like the JavaScript ternary: T extends U ? X : Y. If T is assignable to U, the result is X; otherwise it is Y.

type IsString<T> = T extends string ? "yes" : "no";

type A = IsString<"hello">; // "yes"
type B = IsString<42>;      // "no"

// A practical one: the type of a "message" property, if there is one
type MessageOf<T> = T extends { message: unknown } ? T["message"] : never;

type ErrText = MessageOf<{ message: string; code: number }>; // string
type Nothing = MessageOf<{ code: number }>;                  // never

const a: A = "yes";
const text: ErrText = "disk full";
console.log(a, text); // yes disk full

extends here means "is assignable to", the same relation the compiler uses when you assign a value to a variable. Conditional types exist only at compile time; they are erased from the JavaScript output.

The Syntax

type Result = CheckedType extends TestType ? TrueType : FalseType;

Conditional types become useful with generics, where the checked type is a type parameter that gets a concrete type later. In the true branch TypeScript knows the checked type matches the test, so T["message"] above is allowed even though plain T has no message property.

They also nest, like chained ternaries:

type TypeName<T> =
  T extends string ? "string" :
  T extends number ? "number" :
  T extends boolean ? "boolean" :
  T extends undefined ? "undefined" :
  "object";

function typeName<T>(value: T): TypeName<T> {
  return typeof value as TypeName<T>;
}

console.log(typeName("hi"), typeName(3), typeName(true)); // string number boolean
const n: TypeName<number[]> = "object";
console.log(n); // object

The as TypeName<T> in the function body is not optional, as the next section shows.

Conditional Return Types Need an Assertion

A function whose return type is a conditional type over its own type parameter cannot return either branch directly. TypeScript does not narrow T inside the body, so it cannot tell which branch applies:

// This does not compile: TypeScript cannot pick a branch of Flip<T> inside the body
type Flip<T> = T extends string ? number : string;

function flip<T extends string | number>(x: T): Flip<T> {
  return typeof x === "string" ? x.length : String(x);
}

console.log(flip("abc"), flip(7));

index.ts(5,34): error TS2322: Type 'number' is not assignable to type 'Flip<T>'.
index.ts(5,45): error TS2322: Type 'string' is not assignable to type 'Flip<T>'.

Two common fixes: overloads, which state each input-output pair and check callers precisely, or an assertion in the implementation.

// Fix 1: overloads
function flip(x: string): number;
function flip(x: number): string;
function flip(x: string | number): string | number {
  return typeof x === "string" ? x.length : String(x);
}

const len = flip("abc"); // number
const str = flip(7);     // string
console.log(len + 1, str.padStart(3, "0")); // 4 007

// Fix 2: keep the conditional type and assert inside the body
type Flip<T> = T extends string ? number : string;
function flip2<T extends string | number>(x: T): Flip<T> {
  return (typeof x === "string" ? x.length : String(x)) as Flip<T>;
}
console.log(flip2("hello")); // 5

Overloads are covered on the function overloading page. With an assertion, the compiler trusts you: a wrong branch in the body would not be caught.

Distributive Conditional Types

When the checked type is a bare type parameter and it receives a union, the condition runs once per member and the results are joined into a new union:

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

type A = ToArray<string | number>; // string[] | number[]

// Wrapping both sides in [ ] turns distribution off
type ToArrayWhole<T> = [T] extends [unknown] ? T[] : never;
type B = ToArrayWhole<string | number>; // (string | number)[]

const a: A = ["x", "y"];  // an array of strings, or an array of numbers
const b: B = ["x", 1];    // a mixed array
// const bad: A = ["x", 1] would be error TS2322:
// Type '(string | number)[]' is not assignable to type 'string[] | number[]'.
console.log(a, b); // [ 'x', 'y' ] [ 'x', 1 ]

Distribution is what makes Exclude and Extract work. Exclude<T, U> is defined as T extends U ? never : T: each member that matches U becomes never, and never disappears from a union. So Exclude<"a" | "b" | "c", "a"> is "b" | "c".

Two surprises come from the same rule. boolean is the union true | false, so ToArray<boolean> is false[] | true[], not boolean[]. And never is the empty union, so a distributive conditional type given never returns never without testing anything:

type IsNever<T> = T extends never ? true : false;
type X = IsNever<never>; // never, not true

type IsNeverFixed<T> = [T] extends [never] ? true : false;
type Y = IsNeverFixed<never>; // true

Extracting Types with infer

infer declares a new type variable inside the extends clause. If the match succeeds, TypeScript fills that variable in from the checked type, and you can use it in the true branch:

type ElementOf<T> = T extends readonly (infer E)[] ? E : T;
type Unpromise<T> = T extends Promise<infer V> ? V : T;
type FirstArg<F> = F extends (first: infer A, ...rest: any[]) => unknown ? A : never;
type Head<T> = T extends [infer H, ...unknown[]] ? H : never;

type E1 = ElementOf<string[]>;              // string
type V1 = Unpromise<Promise<{ id: number }>>; // { id: number }
type A1 = FirstArg<(name: string, age: number) => void>; // string
type H1 = Head<[Date, number]>;              // Date

const id: V1 = { id: 7 };
const first: A1 = "Ada";
const when: H1 = new Date("2024-03-15T10:30:00Z");
console.log(id, first, when.toISOString());
// { id: 7 } Ada 2024-03-15T10:30:00.000Z

Read T extends Promise<infer V> ? V : T as "if T is a promise of something, call that something V and return it; otherwise return T unchanged". infer is allowed only in the extends clause of a conditional type.

An infer variable can carry its own constraint with extends. The match then succeeds only if the inferred type fits:

type FirstString<T> = T extends [infer S extends string, ...unknown[]] ? S : never;

type A = FirstString<["a", 1]>; // "a"
type B = FirstString<[1, "a"]>; // never: the first element is not a string

Building ReturnType Yourself

The built-in ReturnType is a one-line conditional type with infer. Writing it yourself is the classic exercise that makes both ideas click:

type MyReturnType<T> = T extends (...args: any[]) => infer R ? R : never;

function makeUser(name: string) {
  return { name, joined: new Date("2024-03-15T10:30:00Z") };
}

type User = MyReturnType<typeof makeUser>; // { name: string; joined: Date }
type Same = ReturnType<typeof makeUser>;   // the built-in gives the same type

const u: User = makeUser("Ada");
const copy: Same = { ...u, name: "Grace" };
console.log(copy.name, copy.joined.getUTCFullYear()); // Grace 2024

typeof makeUser turns the function value into its type, then the conditional type matches it against "any function" and captures the return type as R. The standard library version differs in two details: its parameter is constrained to function types (T extends (...args: any) => any), so ReturnType<string> is a compile error rather than never, and its false branch is any. The ReturnType page covers Parameters, InstanceType and Awaited too.

Recursive Conditional Types

A conditional type can refer to itself, which lets it unwrap any depth of nesting:

type Flatten<T> = T extends readonly (infer U)[] ? Flatten<U> : T;

type A = Flatten<number[][][]>; // number
type B = Flatten<string>;       // string

The built-in Awaited<T> works this way, unwrapping Promise<Promise<T>> down to T. Keep recursion shallow in practice: very deep or unbounded recursion makes the compiler give up with error TS2589: Type instantiation is excessively deep and possibly infinite.

Quick Reference