Type Aliases And Union Types
TypeScript union types let a value be one of several types, such as a string or a number. A type alias gives a name to any type, including unions, so you can reuse it. Together they model real data: a payment can succeed or fail, a shape can be a circle or a square. Mastering them makes your code flexible without losing safety.
This tutorial covers creating aliases with the type keyword, writing unions with |, narrowing a union with typeof and truthiness checks, building discriminated unions with a literal kind field, and choosing between type alias and interface. You will also see the common mistake of accessing a property that exists on only one member of a union.
What Are TypeScript Union Types and Type Aliases?
A TypeScript union type uses the | operator to say a value can be one of several types. A type alias uses the type keyword to give a name to any type. Aliases make unions readable and reusable across your project.
Here is a simple example:
type Id = string | number;
const userId: Id = 101;
const sessionId: Id = "abc-123";
console.log(userId, sessionId);
// Output: 101 abc-123
The Id alias means "a string or a number." Both assignments are valid because both types are part of the union.
How Do You Create a Type Alias with the type Keyword?
A type alias starts with the type keyword, followed by a name, an equals sign, and the type. The name can describe any type, from a primitive to a union to a complex object. The alias itself disappears at compile time.
type UserId = number;
type Username = string;
type Coordinates = [number, number];
const id: UserId = 7;
const name: Username = "Sana";
const point: Coordinates = [12.9, 77.5];
console.log(id, name, point);
// Output: 7 Sana [ 12.9, 77.5 ]
How it works: Each alias names an existing type. UserId is just another name for number, so the compiler treats them the same. Aliases do not create new types at runtime; they are documentation and shorthand. This is useful when a type is long or appears in many places.
How Do Union Types Work with the | Operator?
The | operator combines types into a union. A value typed as A | B can be either an A or a B, but not both at once. The compiler allows only operations that are valid for every member of the union.
type Status = "pending" | "shipped" | "delivered";
function describeStatus(status: Status): string {
return `Order is ${status}.`;
}
console.log(describeStatus("shipped"));
// Output: Order is shipped.
How it works: The union lists three allowed string literals. The parameter status: Status accepts only those three strings. Passing "cancelled" would be a compile error because it is not in the union. This pattern is common for statuses, modes, and roles. You can learn more about string literal unions in the Literal Types tutorial.
How Do You Narrow a Union with typeof and Truthiness?
Narrowing means proving to the compiler which member of the union you have at a particular point. The two common tools are typeof for primitives and truthiness checks for nullable values. After the check, TypeScript allows only the narrowed type's operations.
type Input = string | number | null;
function format(value: Input): string {
if (typeof value === "string") {
return value.toUpperCase();
}
if (typeof value === "number") {
return value.toFixed(2);
}
if (!value) {
return "missing";
}
return String(value);
}
console.log(format("hello"));
console.log(format(3.14159));
console.log(format(null));
// Output: HELLO
// Output: 3.14
// Output: missing
How it works: Each if block narrows value to one type. Inside the first block, value is a string, so .toUpperCase() is allowed. In the second, it is a number, so .toFixed() works. The if (!value) check handles null (and would also handle "" and 0 in other contexts, so be careful with truthiness). After all checks, TypeScript knows the remaining type is never, so the final return is unreachable but safe.
How Do You Build a Discriminated Union with a kind Field?
A discriminated union is a union of object types where each member has a shared literal property that identifies it, usually called kind or type. This lets the compiler narrow the whole object in a switch, giving you full type safety on each branch.
type Shape =
| { kind: "circle"; radius: number }
| { kind: "square"; side: number };
function area(shape: Shape): number {
switch (shape.kind) {
case "circle":
return Math.PI * shape.radius ** 2;
case "square":
return shape.side ** 2;
}
}
const c: Shape = { kind: "circle", radius: 2 };
const s: Shape = { kind: "square", side: 3 };
console.log(area(c).toFixed(2));
console.log(area(s));
// Output: 12.57
// Output: 9
How it works: The Shape union has two object types, each with a distinct kind literal. Inside area, the switch on shape.kind tells the compiler which object it has. In the "circle" case, shape is narrowed to the circle type, so shape.radius is allowed. In the "square" case, shape.side is allowed. Accessing shape.radius in the square case would be a compile error, which is the safety we want. This pattern scales to many variants and is the basis for state machines and API responses.
Type Alias vs Interface: How Do They Differ?
| Feature | Type Alias | Interface |
|---|---|---|
| Define object shapes | Yes | Yes |
| Union types | Yes | No |
| Intersection types | Yes (A & B) |
No (but extends works) |
| Declaration merging | No | Yes |
| Implements in a class | Yes | Yes |
| Call signatures | Yes | Yes |
| Best for | Unions, tuples, mapped types | Object contracts, public APIs |
Use a type alias when you need a union, a tuple, or a mapped type. Use an interface when you are describing an object that may be extended or implemented. The TypeScript Interfaces tutorial covers the interface side. Teams often use both, and mixing them is fine when each is chosen for the right job.
What Is the Common Mistake with Union Property Access?
When a union has members with different properties, you cannot access a property that exists on only one member. The compiler only knows the members share the common fields. Trying to read a member-specific property directly causes an error.
type Result =
| { ok: true; value: string }
| { ok: false; error: string };
function show(result: Result): string {
// return result.value;
// Error: Property 'value' does not exist on type 'Result'.
// Property 'value' does not exist on type '{ ok: false; error: string; }'.
if (result.ok) {
return result.value;
}
return result.error;
}
console.log(show({ ok: true, value: "done" }));
console.log(show({ ok: false, error: "failed" }));
// Output: done
// Output: failed
How it works: The Result union has two variants, one with value and one with error. Accessing result.value directly fails because the false variant does not have value. After checking if (result.ok), TypeScript narrows result to the true variant, so result.value is safe. In the else path, the type is the false variant, so result.error is allowed. This is why discriminated unions always include a shared literal field: it is the key that unlocks narrowing.
Common Mistakes and Best Practices
- Accessing a member-specific property without narrowing. The compiler rejects it because the property may not exist on all members. Add a check like
if (result.ok)or aswitchon the discriminant before accessing. - Forgetting the discriminant field. A union of objects without a shared literal property cannot be narrowed cleanly. Add a
kindortypefield with a distinct string literal for each member. - Using truthiness checks on values that can be
0or"".if (value)treats0and""as false. Useif (value !== null && value !== undefined)when those values are valid. - Using a type alias when you need declaration merging. Type aliases cannot be reopened. If a library needs to extend your type, use an interface instead.
- Building huge unions by hand. Long unions become hard to maintain. Group related members into named aliases and compose them with
|so each piece stays readable.
Real-World Example: A Payment Result
This example uses a discriminated union for payment outcomes and narrows it in a function.
type PaymentResult =
| { kind: "success"; transactionId: string; amount: number }
| { kind: "failed"; reason: string }
| { kind: "pending"; retryAfter: number };
function summarize(result: PaymentResult): string {
switch (result.kind) {
case "success":
return `Paid ${result.amount} (txn ${result.transactionId})`;
case "failed":
return `Failed: ${result.reason}`;
case "pending":
return `Pending, retry in ${result.retryAfter}s`;
}
}
const ok: PaymentResult = { kind: "success", transactionId: "T-101", amount: 499 };
const bad: PaymentResult = { kind: "failed", reason: "card declined" };
console.log(summarize(ok));
console.log(summarize(bad));
// Output: Paid 499 (txn T-101)
// Output: Failed: card declined
How it works, line by line. The PaymentResult union has three variants, each with a distinct kind literal. The summarize function switches on result.kind. In the "success" case, TypeScript narrows result to the success type, so transactionId and amount are available. In "failed", reason is available. In "pending", retryAfter is available. The function returns a string in every case, so the return type stays string. If you tried result.amount in the "failed" case, the compiler would reject it because amount does not exist on that variant. Adding a new variant, such as "refunded", without a matching case would make the function's return type string | undefined, and under strict mode the compiler would flag the missing case.
Summary
- TypeScript union types use
|to say a value can be one of several types. - A type alias with the
typekeyword names any type, including unions and tuples. - Narrow a union with
typeof, truthiness checks, or aswitchon a discriminant. - A discriminated union uses a shared literal field like
kindso the compiler can narrow the whole object. - Choose a type alias for unions and advanced types; choose an interface for extensible object contracts.
- Never access a member-specific property without narrowing first, or the compiler will reject it.
Now that you can combine several possible types, continue to the Intersection Types tutorial to learn how to merge types into one that has all their features.
Frequently Asked Questions
Can a type alias be a union of interfaces?
Yes. Write type Entity = User | Product, where User and Product are interfaces. The alias then names that union. You can narrow the value with a discriminant field or type guards. This pattern is common when a function returns different shapes based on a result.
What is a discriminated union in simple words?
A discriminated union is a union of object types where each member has a shared literal property, usually called kind or type. Because each value has a distinct literal, TypeScript can use a switch on that property to narrow the whole object. This gives full type safety on each branch without casts.
Why can I not access a property on a union directly?
Because the property may not exist on every member of the union. The compiler only allows access to properties shared by all members. To read a member-specific property, narrow the value first with a check like if (result.ok) or a switch on the discriminant. After narrowing, the property is available.
When should I use a type alias instead of an interface?
Use a type alias when you need a union, an intersection, a tuple, or a mapped type. Interfaces cannot represent these. Use an interface when you describe an object that may be extended or implemented by a class, especially in a public API. Both work for simple object shapes, so pick one per team style.
Practice Exercises
Exercise 1 (Easy): Create a Union Type Alias
Create a type alias Contact that is either a string or a number. Assign both a string and a number to variables of that type and print them.
Show solution
type Contact = string | number;
const email: Contact = "riya@example.com";
const phone: Contact = 9876543210;
console.log(email, phone);
// Output: riya@example.com 9876543210
The | operator combines two types, and both values are valid because each matches one member of the union.
Exercise 2 (Easy): Narrow a Union with typeof
Write a function describe that accepts string | number and returns "text" for strings and "number" for numbers.
Show solution
function describe(value: string | number): string {
if (typeof value === "string") {
return "text";
}
return "number";
}
console.log(describe("hello"));
console.log(describe(42));
// Output: text
// Output: number
The typeof check narrows value to a string in the first branch, so the remaining type is number.
Exercise 3 (Medium): Build a Discriminated Union
Create a discriminated union Result with { ok: true; value: number } and { ok: false; error: string }. Write a function that returns the value or error message.
Show solution
type Result =
| { ok: true; value: number }
| { ok: false; error: string };
function unwrap(result: Result): number | string {
if (result.ok) {
return result.value;
}
return result.error;
}
console.log(unwrap({ ok: true, value: 10 }));
console.log(unwrap({ ok: false, error: "not found" }));
// Output: 10
// Output: not found
The ok field is the discriminant. Checking if (result.ok) narrows result so value or error is available in the right branch.
Exercise 4 (Challenge): Shape Area with Exhaustive Switch
Create a Shape union with circle and rectangle variants, each with a kind field. Write an area function with a switch on kind and a default branch that calls assertNever.
Show solution
type Shape =
| { kind: "circle"; radius: number }
| { kind: "rectangle"; width: number; height: number };
function area(shape: Shape): number {
switch (shape.kind) {
case "circle":
return Math.PI * shape.radius ** 2;
case "rectangle":
return shape.width * shape.height;
default:
return assertNever(shape);
}
}
function assertNever(value: never): never {
throw new Error(`Unexpected shape: ${String(value)}`);
}
console.log(area({ kind: "circle", radius: 1 }).toFixed(2));
console.log(area({ kind: "rectangle", width: 2, height: 5 }));
// Output: 3.14
// Output: 10
The default branch calls assertNever, so adding a third variant without a case makes shape not never and triggers a compile error.
Written by Shaikh Abdul Shahid
A Full-Stack Developer with experience in PHP, Laravel, JavaScript, and React.
Founder of Online Learner, sharing practical knowledge and programming tutorials.
Building and maintaining real-world web applications since 2017.
Your Feedback
Help us improve by sharing your thoughts.
Online Learner helps developers master programming, database concepts, interview preparation, and real-world implementation through structured learning paths.
Quick Links
© 2023 - 2026 OnlineLearner.in | All Rights Reserved.
