Conditional types

A type that picks one of two answers

In JavaScript, the conditional operator ? : picks one of two values (the The rest of the operators lesson covers it):

const quantity = 1;
const label = quantity === 1 ? "item" : "items";
console.log(`${quantity} ${label}`);

Line 1 sets quantity to 1. Line 2 asks a question, quantity === 1. If the answer is yes, the label is "item"; if no, it's "items". Line 3 prints 1 item.

TypeScript has the same ? : for types. A conditional type asks a question about a type and picks one of two types as the answer. Here a form field's kind decides what kind of value it holds:

1type FieldValue<Kind> = Kind extends "checkbox" ? boolean : string;2 3type Subscribe = FieldValue<"checkbox">;4//   ^?5type Email = FieldValue<"email">;6//   ^?

Line 1 has four parts:

• FieldValue<Kind> is a type with a type parameter, Kind: a name for a type that you fill in each time you use it, like an argument to a function (the Generic types & interfaces lesson covers them).
• Kind extends "checkbox" is the question: "does Kind fit "checkbox"?"
• ? boolean is the answer for yes. A checkbox is ticked or not, so its value is true or false.
• : string is the answer for no. Every other kind of field holds text.

Line 3 fills in Kind with "checkbox", and the query on line 4 shows the yes answer, boolean. Line 5 uses "email", and the query on line 6 shows the no answer, string. Now pick a kind yourself: type it on line 3 and watch the answer on line 4.

1type FieldValue<Kind> = Kind extends "checkbox" ? boolean : string;2 3type Looked = FieldValue<"checkbox">;4//   ^?

Every kind except "checkbox" gives string, even the type string itself. Without quotes, checkbox isn't a kind at all, so TypeScript reports it. The union "checkbox" | "email" gets both answers; a later section explains why.

extends asks: does it fit?

In a conditional type, A extends B asks: "can every A be used where a B is allowed?" TypeScript calls this being assignable. It doesn't mean "the same as". Four questions:

1type A = "Tea" extends string ? "yes" : "no";2//   ^?3type B = string extends "Tea" ? "yes" : "no";4//   ^?5type C = { name: string; price: number } extends { name: string } ? "yes" : "no";6//   ^?7type D = { name: string } extends { name: string; price: number } ? "yes" : "no";8//   ^?

• Line 1: "Tea" is a string, so it fits string. The query on line 2 shows "yes".
• Line 3 turns it round. A string could be "Cake", so not every string fits "Tea". Line 4 shows "no".
• Line 5: an object with a name and a price has everything { name: string } asks for. Extra properties are fine (the Structural typing lesson explains why). Line 6 shows "yes".
• Line 7: an object with only a name is missing the price, so it doesn't fit. Line 8 shows "no".

You have met extends before, in angle brackets, where it is a rule (the Generic constraints lesson). In a conditional type it is a question. The difference shows when a type doesn't fit:

1function showLabel<T extends string>(label: T) {2  console.log(label);3}4showLabel(3);5 6type IsText<T> = T extends string ? "yes" : "no";7type Three = IsText<3>;8//   ^?

Line 1 says T extends string in angle brackets: a rule, called a constraint, that label must be text. Line 4 passes 3, so TypeScript reports Argument of type 'number' is not assignable to parameter of type 'string', on purpose here. Line 6 uses T extends string as a question. Line 7 passes 3 too, and nothing is wrong: the query on line 8 just shows the no answer, "no".

The table below compares the two. Read each row as: where extends is written, what it means there, and what happens when a type doesn't fit.

Conditional types with type parameters

A question about two fixed types, like "Tea" extends string, always has the same answer, so you could just write the answer. Conditional types are useful with a type parameter, where the answer depends on the type passed in.

Say you want the item type of an array. The Indexed access types lesson used Cart[number]. With a type parameter, that is an error on purpose here:

1type ItemOf<T> = T[number];

TypeScript says Type 'number' cannot be used to index type 'T'. T could be any type, like boolean, which has no items to look up. A conditional type can check first:

1type Flatten<T> = T extends unknown[] ? T[number] : T;2 3type Tag = Flatten<string[]>;4//   ^?5type Count = Flatten<number>;6//   ^?

Line 1 asks whether T fits unknown[], an array of anything. In the yes branch, TypeScript knows T is an array, so T[number] is allowed. In the no branch, Flatten gives T back unchanged. Line 3 passes a list of strings, and the query on line 4 shows the item type, string. Line 5 passes number, which isn't an array, and line 6 shows number.

The same works for any property. Here is a type that reads the message from an API error, if it has one:

1type ErrorText<T> = T extends { message: string } ? T["message"] : "Unknown error";2 3type Declined = ErrorText<{ message: "Card declined"; code: number }>;4//   ^?5type ServerDown = ErrorText<{ status: 500 }>;6//   ^?

Line 1 asks whether T has a message that is text. If so, it looks the message up with T["message"]; if not, the answer is the text type "Unknown error". Line 3's error has a message, and the query on line 4 shows "Card declined". Line 5's error has only a status, and line 6 shows "Unknown error".

One question gives two answers. For more, put another conditional type in the no branch. Each : leads to the next question:

1type FieldValue<Kind> =2  Kind extends "checkbox" ? boolean :3  Kind extends "number" ? number :4  string;5 6type Age = FieldValue<"number">;7//   ^?8type Subscribe = FieldValue<"checkbox">;9//   ^?10type Email = FieldValue<"email">;11//   ^?

Lines 1 to 4 are one type. Line 2 asks about "checkbox"; if no, line 3 asks about "number"; if no again, line 4 gives string. The queries on lines 7, 9, and 11 show number, boolean, and string. TypeScript reads the questions in order and stops at the first yes, like else if.

Unions are checked one member at a time

In the overview, the union "checkbox" | "email" got both answers. When you pass a union to a type parameter that stands alone before extends, TypeScript splits the union, asks the question for each member, and joins the answers:

1type FieldValue<Kind> = Kind extends "checkbox" ? boolean : string;2 3type Mixed = FieldValue<"checkbox" | "email">;4//   ^?

Line 3 passes "checkbox" | "email". TypeScript works out FieldValue<"checkbox">, which is boolean, and FieldValue<"email">, which is string. The query on line 4 shows the two joined: string | boolean. This is called a distributive conditional type: the question is handed out to each member, the way you hand out one card to each person at a table.

Splitting is useful for filtering a union. The answer never means "no type at all" (the any, unknown & never lesson covers it), and a union drops it, because it adds nothing. So answer never for the members you don't want:

1type FieldKind = "text" | "email" | "checkbox" | "number";2 3type TextLike<Kind> = Kind extends "text" | "email" ? Kind : never;4 5type TextKinds = TextLike<FieldKind>;6//   ^?

Line 1 lists four field kinds. Line 3 keeps a kind if it fits "text" | "email", and answers never otherwise. Line 5 passes all four. "checkbox" and "number" become never and disappear, and the query on line 6 shows "text" | "email". TypeScript's own Extract and Exclude types work this way; you'll meet them in the ReturnType, Awaited & more lesson. Change what line 3 keeps:

1type FieldKind = "text" | "email" | "checkbox" | "number";2 3type Picked<Kind> = Kind extends "text" | "email" ? Kind : never;4 5type Result = Picked<FieldKind>;6//   ^?

Each button changes only line 3, and the query on line 6 always shows the members that fit. When none fit, every member becomes never, and so does the result.

Check a union as a whole

Sometimes you want one answer about the whole union. Wrap both sides of extends in square brackets. [T] is a tuple with one item (the Arrays & tuples lesson covers tuples), so T no longer stands alone, and the union isn't split:

1type ToArray<T> = T extends unknown ? T[] : never;2type Split = ToArray<string | number>;3//   ^?4 5type ToArrayWhole<T> = [T] extends [unknown] ? T[] : never;6type Whole = ToArrayWhole<string | number>;7//   ^?

Line 1 asks T extends unknown. Every type fits unknown, so the answer is always T[]; the question is only there to split the union. Line 2 passes string | number, and the query on line 3 shows string[] | number[]: a list of strings or a list of numbers. Line 5 wraps both sides: [T] extends [unknown]. Line 6 passes the same union, and the query on line 7 shows (string | number)[]: one list that can hold both.

The two forms can give quite different answers. Here IsText asks three questions. Press the buttons to switch line 1 between the two forms:

1type IsText<T> = T extends string ? "yes" : "no";2 3type One = IsText<"email">;4//   ^?5type Mixed = IsText<"email" | 3>;6//   ^?7type Nothing = IsText<never>;8//   ^?

For "email", both forms say "yes". For "email" | 3, the split form asks twice and gets "yes" | "no", while the whole form asks once and says "no". For never, the split form has no members to ask, so the answer is never, while the whole form says "yes", because never fits every type.

The table below puts the answers side by side. Read each row as: the input, then the answer from each form.

A form reader whose return type follows the field

A form helper reads a field and gives back its value: true or false for a checkbox, a number for a number box, and text for the rest. A conditional type can say that in the return type. Written plainly, the function gets errors, on purpose here:

1type FieldKind = "text" | "number" | "checkbox";2type FieldValue<Kind> = Kind extends "checkbox" ? boolean : Kind extends "number" ? number : string;3type Input = { value: string; checked: boolean };4 5function readField<Kind extends FieldKind>(kind: Kind, input: Input): FieldValue<Kind> {6  if (kind === "checkbox") return input.checked;7  if (kind === "number") return Number(input.value);8  return input.value;9}

Lines 1 to 3 describe the field kinds, the value for each kind, and an input with a value and a checked. Line 5 says readField gives back FieldValue<Kind>. Lines 6, 7, and 8 each get an error like Type 'boolean' is not assignable to type 'FieldValue<Kind>'. Inside the function, Kind isn't known yet, so TypeScript can't pick a branch, and checking kind === "checkbox" doesn't tell it which one either.

The usual fix is a type assertion, as FieldValue<Kind>, which tells TypeScript "trust me, this value has that type" (the Type assertions lesson covers as). It moves the checking to you, so keep each branch short:

1type FieldKind = "text" | "number" | "checkbox";2type FieldValue<Kind> = Kind extends "checkbox" ? boolean : Kind extends "number" ? number : string;3type Input = { value: string; checked: boolean };4 5function readField<Kind extends FieldKind>(kind: Kind, input: Input): FieldValue<Kind> {6  if (kind === "checkbox") return input.checked as FieldValue<Kind>;7  if (kind === "number") return Number(input.value) as FieldValue<Kind>;8  return input.value as FieldValue<Kind>;9}10 11const ageBox = { value: "30", checked: false };12const age = readField("number", ageBox);13//    ^?14const subscribed = readField("checkbox", { value: "on", checked: true });15//    ^?16console.log(age + 1, subscribed);

Lines 6 to 8 add as FieldValue<Kind>, and the errors are gone. The payoff is at each call. Line 12 reads a number box, and the query on line 13 shows const age: number, so age + 1 is safe. Line 14 reads a checkbox, and line 15 shows boolean. Line 16 prints 31 true. Each caller gets the exact type for its field, with no assertion of its own.

Common mix-ups

Only a type parameter that stands alone splits a union. Write the union out, and it is asked about once:

1type IsText<T> = T extends string ? "yes" : "no";2 3type ViaParameter = IsText<string | number>;4//   ^?5type WrittenOut = string | number extends string ? "yes" : "no";6//   ^?

Line 3 passes string | number to IsText, so the union is split, and the query on line 4 shows "yes" | "no". Line 5 writes the same question with the union itself before extends. There is no type parameter, so nothing is split: the whole union isn't text, and line 6 shows "no".

• "extends here means one class inherits from another." No. In a conditional type it asks whether one type fits another, for any types: "Tea" extends string is yes.
• "A extends B asks whether the two types are the same." No. It asks whether every A can be used as a B. string extends "Tea" is no, but "Tea" extends string is yes.
• "A conditional type runs like an if while the page runs." No. TypeScript picks the answer as it checks your code, and the type is removed before the code runs.
• "Every union is split." No. Only a type parameter that stands alone before extends splits a union. A union written out, or wrapped as [T], is asked about once.
• "never takes the no branch." No. With a split, never is an empty union, so the answer is never.
• "TypeScript checks a function's body against a conditional return type." No. Inside the function it can't pick a branch, so you write as, and checking each branch is up to you.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code: the errors and ^? answers update as you type. Try a guess first, then use the hints.

1type IsList<T> = T extends unknown[] ? "list" : "single";2 3type Cart = IsList<string[]>;

1type IsList<T> = T extends unknown[] ? "list" : "single";2 3type Cart = IsList<string[]>;4//   ^?

1type Fits = { id: number } extends { id: number; name: string } ? "yes" : "no";

1type Fits = { id: number } extends { id: number; name: string } ? "yes" : "no";2//   ^?

1type ApiData<T> = unknown; // write a conditional type here2 3type User = ApiData<{ data: { name: string }; status: 200 }>;4//   ^?5type Failed = ApiData<{ error: string; status: 500 }>;6//   ^?

1type ApiData<T> = T extends { data: unknown } ? T["data"] : never;2 3type User = ApiData<{ data: { name: string }; status: 200 }>;4//   ^?5type Failed = ApiData<{ error: string; status: 500 }>;6//   ^?

type First<T> = T extends unknown[] ? T[0] : T;
type Last<T> = T[number];

1type First<T> = T extends unknown[] ? T[0] : T;2type Last<T> = T extends unknown[] ? T[number] : T;

1type OnlyNumbers<T> = T; // keep only the numbers2 3type Prices = OnlyNumbers<3 | "Tea" | 4>;4//   ^?

1type OnlyNumbers<T> = T extends number ? T : never;2 3type Prices = OnlyNumbers<3 | "Tea" | 4>;4//   ^?

1type AllText<T> = T extends string ? true : false;2 3type Check = AllText<"Tea" | 3>;4//   ^?

1type AllText<T> = [T] extends [string] ? true : false;2 3type Check = AllText<"Tea" | 3>;4//   ^?

Check your understanding

For each question, find the question the type asks, then ask: is a union split here? The quiz shows its code without the checker, so the answers aren't shown on the page.

Key takeaways

• A extends B ? X : Y picks X if A fits B, and Y otherwise.
• "Fits" means every A can be used as a B: "Tea" extends string is yes, the other way round is no.
• In angle brackets, extends is a rule that reports errors. Before ?, it is a question that picks an answer.
• Conditional types are useful with type parameters. In the yes branch, TypeScript knows more, so lookups like T[number] work.
• A union passed to a type parameter that stands alone is split, asked member by member, and joined. Answer never to drop members.
• [T] extends [U] asks about the whole union once.
• The choice is made while TypeScript checks, not while the page runs.

Coming next: The infer keyword. It lets the question in a conditional type capture a part of the type, like a function's return type, and use it in the answer.