TypeScript Union Types: The | Operator with Examples

A union type lists alternatives with |: a value of type string | number is either a string or a number. Unions are how TypeScript describes values that can legitimately take more than one form, and the compiler makes you check which form you have before using anything specific to it.

function formatId(id: string | number): string {
  if (typeof id === "number") {
    return id.toString().padStart(6, "0"); // id is number here
  }
  return id.toUpperCase();                 // id is string here
}

console.log(formatId(42));     // 000042
console.log(formatId("ab-7")); // AB-7

Inside each branch of the typeof check, id has a single type. That step is called narrowing, and it is what makes unions practical.

Only Common Members Are Allowed

Before narrowing, you can only use what every member of the union supports. toString() exists on both strings and numbers, so it is fine; toUpperCase() exists only on strings:

// This does not compile: numbers have no toUpperCase()
function shout(value: string | number) {
  return value.toUpperCase();
}

console.log(shout("hi"));

index.ts(3,16): error TS2339: Property 'toUpperCase' does not exist on type 'string | number'.
  Property 'toUpperCase' does not exist on type 'number'.

The second line names the member that is missing the property. The same rule applies in the other direction: a string | number value cannot be passed to a parameter typed string (TS2345), because it might be a number. A union accepts more values, and in exchange lets you do less with them until you check.

Narrowing a Union

Narrowing uses ordinary JavaScript checks. TypeScript follows the control flow and removes members as they are ruled out, so after the last check only one member is left:

type Input = string | number | string[] | Date | null;

function normalize(input: Input): string {
  if (input === null) return "(empty)";
  if (typeof input === "string") return input.trim();
  if (typeof input === "number") return input.toFixed(1);
  if (Array.isArray(input)) return input.join(", ");
  return input.toISOString().slice(0, 10); // only Date is left
}

const samples: Input[] = ["  hi  ", 3, ["a", "b"], new Date("2024-03-15T10:30:00Z"), null];
for (const s of samples) console.log(normalize(s));
// hi
// 3.0
// a, b
// 2024-03-15
// (empty)

The full list of narrowing forms is on the type narrowing page.

Unions of Literal Types

A union of literal values is a closed set of allowed values. It is the most common union in real code:

type Status = "idle" | "loading" | "success" | "error";
type Dice = 1 | 2 | 3 | 4 | 5 | 6;
type Toggle = "on" | "off" | boolean; // boolean is itself true | false

let current: Status = "idle";
current = "loading";   // fine
current = "finished";  // error TS2322: Type '"finished"' is not assignable to type 'Status'.

Comparing against a literal narrows: after if (current === "error"), the else branch knows current is one of the other three. Literal unions replace enums in many codebases; see literal types for as const and how to derive such a union from an array.

Unions of Object Types

When the members are object types, properties they all share are available directly. For the rest, check that the property exists with in:

type Cat = { name: string; meow(): string };
type Fish = { name: string; swim(): string };

function act(pet: Cat | Fish): string {
  const intro = `${pet.name}: `; // name exists on both, so it is allowed
  if ("meow" in pet) {
    return intro + pet.meow();   // pet is Cat here
  }
  return intro + pet.swim();     // pet is Fish here
}

const tom: Cat = { name: "Tom", meow: () => "meow" };
const nemo: Fish = { name: "Nemo", swim: () => "swims away" };

console.log(act(tom));  // Tom: meow
console.log(act(nemo)); // Nemo: swims away

For unions of several object shapes, the cleaner pattern is a shared literal property such as kind: "cat" / kind: "fish". Checking that one property narrows the whole object, and switch over it can be checked for exhaustiveness. That pattern is a discriminated union.

Arrays and Unions

Where the parentheses go changes the meaning completely:

const mixed: (string | number)[] = [1, "two", 3]; // each element may be either
const eitherOr: string[] | number[] = ["a", "b"]; // all strings OR all numbers

// @ts-expect-error: Type '(string | number)[]' is not assignable to type 'string[] | number[]'.
const bad: string[] | number[] = ["a", 1];

const precedence: string | number[] = "not an array"; // | binds looser than []

console.log(mixed, eitherOr, precedence);
// [ 1, 'two', 3 ] [ 'a', 'b' ] not an array

const total = mixed.reduce<number>((sum, x) => sum + (typeof x === "number" ? x : 0), 0);
console.log(total); // 4

When iterating a (string | number)[], each element is the union and needs narrowing, as in the reduce callback above. Methods like map and filter also work on a string[] | number[], with the callback receiving string | number.

Unions with null and undefined

The most common union of all is "a value or nothing": string | null, User | undefined. It is what Array.prototype.find and Map.prototype.get return, and an optional property name?: string reads as string | undefined. Handling these with ?., ?? and null checks has its own page: null and undefined.

To remove members from an existing union at the type level, use the built-in utilities: Exclude<"a" | "b" | "c", "a"> is "b" | "c", and NonNullable<string | null> is string.