Union types

One value, more than one type

A shop page shows an order. Older orders have a number for an ID, like 42. Newer ones arrive from the page address as text, like "A-42". In plain JavaScript, one variable can hold either. TypeScript isn't so sure:

1let orderId = 42;2//  ^?3orderId = "A-42";

Line 1 stores 42. Line 2 is a question for TypeScript: // ^? asks "what type is the name my ^ points at?", and the page writes the answer after it: let orderId: number. You didn't write a type, so TypeScript worked one out from the first value. Line 3 stores text, and TypeScript marks it, on purpose here: Type 'string' is not assignable to type 'number'. In plain words: "this variable holds numbers, and you're putting text in it".

You want to say "text or a number". That's what a union type is. You write the types with a | between them, and you read the | as "or":

1let orderId: string | number = 42;2//  ^?3orderId = "A-42";4console.log(orderId);5orderId = true;

Line 1 says orderId is a string | number: text or a number. It starts as 42, and the query on line 2 shows the type you wrote. Line 3 stores "A-42", and this time there's no error. Line 4 prints A-42. Line 5 tries true, which is a boolean (a true-or-false value). TypeScript marks it, on purpose: Type 'boolean' is not assignable to type 'string | number'. A boolean is neither of the two types the union lists. Each type in a union is called a member, so this union has two members.

Now try it yourself. Type a value for line 1 and watch the list under the code as you type.

1let orderId: string | number = true;2console.log(orderId);

42 and "A-42" have no errors, because each one matches a member. true, null, and [42] each get an error, because none of them is text or a number. An empty box gets Expression expected, because line 1 needs a value.

Using a value that could be either

Storing a value in a union is easy: give it any member type. Using the value is where TypeScript gets careful. Here is a function that shows an order ID in capital letters:

1function showOrderId(orderId: string | number) {2  console.log(orderId.toUpperCase());3}4 5showOrderId("a-42");

Line 1 says orderId is text or a number. Line 2 calls toUpperCase(), a method that only text has. Line 5 calls the function with "a-42", which works and prints A-42. But TypeScript marks line 2 on purpose, with two lines of message:

• Property 'toUpperCase' does not exist on type 'string | number' means "you can't be sure this value has a toUpperCase". A property is anything you read with a dot, and methods count.
• Property 'toUpperCase' does not exist on type 'number' names the member that lacks it. If someone calls showOrderId(42), the code throws a TypeError and stops.

The rule is simple: with a union, you can only do what every member can do. Try different things on line 2. Each button swaps that one line; the code then calls the function with text and with a number.

1function showOrderId(orderId: string | number) {2  console.log(orderId.toUpperCase());3}4 5showOrderId("a-42");6showOrderId(42);

toUpperCase() and toFixed(1) each belong to one member, so each gets an error, and each throws for the other member. .length gets an error too; plain JavaScript would quietly print undefined. + 1 gets an error because it adds to a number but joins to text. toString() and the template literal work for both, so there are no errors. The table below sums it up. Read each row as: this code, is it allowed on a string | number, and why.

To use a string method, you first check that you have a string. JavaScript's typeof operator gives the kind of a value as text, like "string" or "number" (the Checking types lesson covers it). TypeScript reads your typeof check:

1function formatOrderId(orderId: string | number) {2  if (typeof orderId === "string") {3    return orderId.toUpperCase();4    //     ^?5  }6  return "#" + orderId;7  //           ^?8}9 10console.log(formatOrderId("a-42"));11console.log(formatOrderId(42));

Line 2 asks whether orderId is text. Inside that if, the query on line 4 shows (parameter) orderId: string: TypeScript knows it's text there, so line 3 may call toUpperCase(). Line 3 also leaves the function with return, so line 6 runs only for numbers, and the query on line 7 shows (parameter) orderId: number. Line 10 prints A-42 and line 11 prints #42.

Turning a wide type into a more exact one with a check like this is called narrowing. TypeScript understands many checks, and the Narrowing lessons in the next stage, starting with Narrowing with typeof & truthiness, cover them one by one. For now, typeof is all you need.

Unions of object types

A union can join object types too. A search box asks a server for products. The server sends one of two replies: the products it found, or a message saying why it failed. Each reply is an object with its own properties:

1type Found = { status: number; results: string[] };2type Failed = { status: number; message: string };3 4function showReply(reply: Found | Failed) {5  console.log(reply.status);6  console.log(reply.results);7}8 9showReply({ status: 404, message: "No products found" });

Lines 1 and 2 give names to two object types with type. type Found = … means "from now on, Found stands for this object type" (the Type aliases & interfaces lesson covers this). A Found reply has a status and a list of results. A Failed reply has a status and a message. Line 4 says reply is either one.

Line 5 reads reply.status, and that's fine: both replies have it. Line 6 reads reply.results, and TypeScript marks it on purpose: Property 'results' does not exist on type 'Found | Failed', and on its second line, Property 'results' does not exist on type 'Failed'. Line 9 shows why: a failed reply has no results, so line 5 prints 404 and line 6 prints undefined.

It's the same rule as before. A Found | Failed value could be either object, so you can read only the properties both have. To read the others, check which object you have. JavaScript's in operator asks whether an object has a property (Object basics covers it), and TypeScript reads that check too (the in & instanceof narrowing lesson goes further):

1type Found = { status: number; results: string[] };2type Failed = { status: number; message: string };3 4function showReply(reply: Found | Failed) {5  if ("results" in reply) {6    console.log(reply.results.join(", "));7    //          ^?8  } else {9    console.log(reply.message);10    //          ^?11  }12}13 14showReply({ status: 200, results: ["Tea", "Cake"] });15showReply({ status: 404, message: "No products found" });

Line 5 asks whether reply has a results property. Only Found has one, so inside the if, the query on line 7 shows (parameter) reply: Found, and line 6 may read the results. In the else, only Failed is left: the query on line 10 shows (parameter) reply: Failed, and line 9 reads the message. Line 14 prints Tea, Cake, and line 15 prints No products found.

Unions in parameters, results, and lists

Unions show up most in function parameters, where you want to accept more than one kind of input. A price might come from the server as a number, or from a form as text:

1function formatPrice(price: string | number) {2  return `$${Number(price).toFixed(2)}`;3}4 5console.log(formatPrice(4));6console.log(formatPrice("4.5"));7console.log(formatPrice(true));

Line 1 says formatPrice takes a price that is text or a number. Line 2 turns it into a number with Number(price), which works for both, and writes it with two decimals. Line 5 passes 4 and prints $4.00. Line 6 passes "4.5" and prints $4.50. Line 7 passes true, and TypeScript marks it on purpose: Argument of type 'boolean' is not assignable to parameter of type 'string | number'. An argument is a value you pass in a call, and a parameter is the name that receives it. Plain JavaScript would print $1.00, because Number(true) is 1.

TypeScript also gives you unions, when a value really could be one of two things. You met one in the Arrays & tuples lesson: find gives back a matching item, or undefined when nothing matches.

1const prices = [3, 4, 5];2const firstBig = prices.find((price) => price > 3);3//    ^?4console.log(firstBig);

Line 1 makes a list of prices. Line 2 looks for the first price above 3. The query on line 3 shows const firstBig: number | undefined: a number if one matches, undefined if none does. Line 4 prints 4. The null, undefined & strictNullChecks lesson shows how to handle the undefined part.

Lists can hold a union too. When a list mixes text and numbers, TypeScript works out a union for its items:

1const sizes = [8, "M", 10];2//    ^?3sizes.push("L");4sizes.push(true);

Line 1 makes a list of clothing sizes: 8, "M", and 10. The query on line 2 shows const sizes: (string | number)[], which means "a list where each item is text or a number". Line 3 adds "L", which is fine. Line 4 tries to add true, and TypeScript marks it on purpose: Argument of type 'boolean' is not assignable to parameter of type 'string | number'.

The round brackets in (string | number)[] matter. Without them, [] applies to number alone. The table below compares three types that look alike. Read each row as: this type, what it means, and whether it can hold the list [8, "M"].

When a union gets long, you can put each member on its own line. A | is allowed before the first member, so every line starts the same way:

1function setPageSize(2  size:3    | number4    | string,5) {6  console.log(`Showing ${size} items`);7}8 9setPageSize(20);10setPageSize("20");

Lines 2 to 4 say size is a number or a string, exactly like number | string on one line. Lines 9 and 10 both print Showing 20 items.

A search box that finds by id or name

A shop's search box lets people find a product by its number or by its name. One function handles both, with a union parameter and a typeof check:

1const products = [2  { id: 7, name: "Tea" },3  { id: 8, name: "Cake" },4];5 6function findProduct(query: string | number) {7  if (typeof query === "number") {8    return products.find((product) => product.id === query);9  }10  return products.find((product) => product.name.toLowerCase() === query.toLowerCase());11}12 13console.log(findProduct(8)?.name);14console.log(findProduct("tea")?.name);

Lines 1 to 4 make two products. Line 6 says query is text or a number. Line 7 checks for a number; inside, line 8 compares it with each product's id. Line 10 runs only for text, so query.toLowerCase() is allowed there, and it compares names without caring about capital letters. Line 13 finds product 8 and prints Cake. Line 14 finds "tea" and prints Tea. The ?. reads name only if a product was found (Nullish and optional chaining covers it).

Where does the union come from? A text box always gives text. The page can turn digits into a number and keep anything else as text, and TypeScript works out the union by itself:

1const searchBox = document.createElement("input");2searchBox.value = "8";3 4const typed = searchBox.value;5const query = Number.isNaN(Number(typed)) ? typed : Number(typed);6//    ^?7console.log(query);

Lines 1 and 2 make a text box and put "8" in it, as if someone typed 8. (The Form elements lesson covers inputs.) Line 4 reads the text. Line 5 asks whether Number(typed) is NaN ("not a number"). If it is, query keeps the text; if not, it gets the number. The query on line 6 shows const query: string | number, because either could happen. Line 7 prints 8, and that query is ready to pass to findProduct.

Common mix-ups

The order of a union's members doesn't matter. TypeScript may even show them in a different order from yours:

1let price: number | string = 4;2//  ^?

Line 1 says number | string. The query on line 2 shows let price: string | number. It's the same type: both say "text or a number".

• "string | number means the value is both." No. It's one or the other at any moment. The | reads "or".
• "If a union includes string, I can use string methods." No. You can use only what every member has, until a check like typeof orderId === "string" narrows it.
• "A union converts my value." No. Types are removed before the code runs. formatPrice still needs Number(price) to turn text into a number.
• "string | number[] is a list of text or numbers." No. That's one piece of text, or a list of numbers. A list of either is (string | number)[], with brackets.
• "With a union of objects, I can read any property from either one." No. Only properties every object has, like status. Check with in before reading the rest.
• "number | string and string | number are different types." No. The order doesn't matter, as the query above shows.

Practice exercises

Each exercise is TypeScript. When you fix code, press Edit & run on the starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

let discount: string | number = 10;
discount = "10%";
discount = false;
discount = 5;

1let discount: string | number = 10;2discount = "10%";3discount = false; // line 3: a boolean is neither text nor a number4discount = 5;

1const sizes = ["S", 10, "L"];

1const sizes = ["S", 10, "L"];2//    ^?

1let productId: number = 7;2console.log(productId);3productId = "tea-7";4console.log(productId);

1let productId: string | number = 7;2console.log(productId);3productId = "tea-7";4console.log(productId);

1function shout(label: string | number) {2  return label.toUpperCase();3}4 5console.log(shout("sale"));6console.log(shout(7));

1function shout(label: string | number) {2  if (typeof label === "string") {3    return label.toUpperCase();4  }5  return String(label);6}7 8console.log(shout("sale"));9console.log(shout(7));

1type Card = { method: string; last4: string };2type Cash = { method: string; amount: number };3 4function describe(payment: Card | Cash) {5  return `Paid by ${payment.method}, card ending ${payment.last4}`;6}7 8console.log(describe({ method: "card", last4: "4242" }));9console.log(describe({ method: "cash", amount: 20 }));

1type Card = { method: string; last4: string };2type Cash = { method: string; amount: number };3 4function describe(payment: Card | Cash) {5  if ("last4" in payment) {6    return `Paid by ${payment.method}, card ending ${payment.last4}`;7  }8  return `Paid by ${payment.method}: $${payment.amount}`;9}10 11console.log(describe({ method: "card", last4: "4242" }));12console.log(describe({ method: "cash", amount: 20 }));

1let cartCount = 0;2 3function addToCart(quantity: number) {4  cartCount += quantity;5}6 7addToCart(2);8addToCart("3");9console.log(cartCount);

1let cartCount = 0;2 3function addToCart(quantity: string | number) {4  cartCount += Number(quantity);5}6 7addToCart(2);8addToCart("3");9console.log(cartCount);

Check your understanding

For each question, ask which member types a value could have, and whether the code works for every one of them. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A union type says a value can be one of several types: string | number is text or a number.
• Any value of a member type fits. Anything else, like true or null, gets an error.
• You can use only what every member can do, like toString(), until you check.
• A typeof check, or in for objects, narrows the union to one member inside the check.
• Union parameters let one function accept several kinds of input; you still convert the value yourself.
• TypeScript works out unions too: number | undefined from find, (string | number)[] for a mixed list.

Coming next: Literal types. A type can be one exact value, like "small", and a union of those makes a list of allowed options.