Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 96 ยท Basic Types

Type Aliases

Learn TypeScript type aliases - naming object, union, tuple and function types, generic and recursive aliases like a JSON type, and when to name a type.

By now you've written types like { id: number; name: string; email?: string } and 'light' | 'dark' | 'system' more than once. Repeating a type in five places is tedious, and worse, the copies drift apart when one of them changes. A type alias gives a type a name, so you write it once and use the name everywhere:

TypeScript
type Theme = 'light' | 'dark' | 'system';

You've already seen aliases in passing in Union Types and Literal Types and as const. This lesson explains them properly: what you can name, the important fact that an alias is only a name, generic and recursive aliases (including a type for any JSON value), and how to decide when a type deserves a name.

The type keyword

A type alias starts with type, then a name in PascalCase, an = and any type at all:

TypeScript Naming different kinds of types

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

The output is the ada object and Ada is 75% done. Notice how User is built from other aliases. Once a type has a name, it composes like a building block, and the code reads like a description of your data.

Also notice that toPercent's parameter has no annotation. Because the variable is typed as Formatter, TypeScript already knows value is a number (contextual typing). Function types are covered fully in Function Types and Callbacks.

Aliases are a purely compile-time feature. The type lines vanish completely from the JavaScript output, so they cost nothing at runtime. That also means you can't use an alias as a value: console.log(Theme) is error TS2693, "'Theme' only refers to a type, but is being used as a value here".

An alias is a name, not a new type

This is the most important fact about aliases, and it often surprises people coming from other languages. type UserId = number does not create a new kind of number. It's just another name for number, and the two are completely interchangeable:

TypeScript Aliases of the same type are interchangeable

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

This prints Deleting user 501, Deleting user 42 and { value: 100 }. Passing a product ID to deleteUser might be a serious bug, but TypeScript can't catch it, because it compares types by structure, not by name. (This is the same structural typing you met in Object Types.)

So why use UserId at all? Because names are documentation. function deleteUser(id: UserId) tells readers what kind of number to pass, and if user IDs change to strings one day, you update one line. When you truly need the compiler to keep two such types apart, there's a pattern called branded types, which you'll learn in Type Compatibility and Variance.

Error messages and editor tooltips usually show the alias name (Type 'string' is not assignable to type 'Theme') rather than the expanded type. That's another good reason to name complex types: the messages become much easier to read.

Naming unions and function types

Aliases are the only way to name a union or a function type for reuse (interfaces, coming next, describe object shapes). Two patterns appear everywhere:

TypeScript Aliases for callbacks and results

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

The output is [ 'Toaster', 'Kettle', 'Blender' ], [ 'Blender', 'Kettle', 'Toaster' ], price: 19.99 and error: "free" is not a valid price.

Comparator<T> is a generic alias: T is a placeholder that you fill in when you use the alias, as in Comparator<Product>. Generic aliases let one name describe a whole family of types. Two tiny ones you'll write again and again:

TypeScript
type Maybe<T> = T | null;
type Pair<T> = [first: T, second: T];

const middleName: Maybe<string> = null;
const corners: Pair<{ x: number; y: number }> = [{ x: 0, y: 0 }, { x: 10, y: 5 }];

Generics and Generic Interfaces, Classes and Types explain type parameters in depth.

ParseResult is a discriminated union (the ok property tells the cases apart), the shape behind the popular Result pattern for error handling without exceptions. You'll build more of these in Discriminated Unions.

Combining aliases with &

The & operator creates an intersection type: a value must satisfy both sides. For object types, that means it has all the properties of both. It's a simple way to build bigger shapes from smaller ones:

TypeScript Building shapes with intersections

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

This prints Type aliases in practice updated 2026-10-18. Because an Article has every property of Timestamps, it can be passed to lastChanged. Leave out any property, say updatedAt, and you get the familiar TS2741 "Property is missing" error. Intersections of incompatible types, such as string & number, collapse to never, as you saw in any, unknown, never and void. Object Types in Depth covers intersections and their edge cases.

Recursive aliases

An alias can refer to itself. That's how you describe data that nests to any depth, like a file tree, a comment thread or a menu. The classic example is a type for any value that JSON.stringify can produce:

TypeScript A type for any JSON value

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

The program prints 8 (id, paid, two sku/qty pairs, color and note) and the JSON string's length, 119. Inside countLeaves, the checks narrow value step by step: first to an array, then to an object, and finally to the primitives that remain.

The recursive type also rejects values JSON can't represent:

TypeScript Values that aren't JSON (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TEXT
main.ts(9,7): error TS2322: Type '{ createdAt: Date; }' is not assignable to type 'JsonValue'.
  Types of property 'createdAt' are incompatible.
    Type 'Date' is not assignable to type 'JsonValue | undefined'.
      Type 'Date' is not assignable to type '{ [key: string]: JsonValue; }'.
        Index signature for type 'string' is missing in type 'Date'.
main.ts(10,7): error TS2322: Type '{ format: () => string; }' is not assignable to type 'JsonValue'.
  Types of property 'format' are incompatible.
    Type '() => string' is not assignable to type 'JsonValue | undefined'.
main.ts(11,7): error TS2322: Type '{ size: undefined; }' is not assignable to type 'JsonValue'.
  Type '{ size: undefined; }' is not assignable to type 'null'.

Read nested messages from the top down: each indented line explains the line above it. The last message looks odd, because TypeScript explains the failure by comparing the object with just one of the union's members (null); the real reason is that undefined isn't a valid property value. These are real JSON pitfalls: JSON.stringify turns a Date into a string (so it won't come back as a Date), drops functions, and drops properties whose value is undefined. The type makes those surprises visible. The JavaScript lesson on JSON shows the runtime side.

Recursion works when the self-reference sits inside an object, array, tuple or function type, as above. A directly circular alias like type Loop = Loop | string is an error (TS2456, "Type alias 'Loop' circularly references itself"). Advanced Type-Level Programming uses recursive aliases for much fancier tricks.

When to name a type

Not every type needs an alias. Some guidelines:

Name it when:

  • It's used in more than one place (the main reason).
  • It represents a concept in your domain: Order, Theme, Money, UserId.
  • It's long enough to clutter a function signature, such as a union of five object shapes.
  • You want readable error messages and tooltips.

Keep it inline when:

  • It's a small, one-off shape, for example an options parameter used by a single function: function resize(size: { width: number; height: number }).
  • The type is obvious from context, like string[] or number | null.

Naming is also a design tool. If you can't think of a good name for a type, it may be combining two unrelated ideas.

Type aliases vs interfaces

The next lesson introduces interfaces, another way to name object shapes:

TypeScript
type PointType = { x: number; y: number };
interface PointInterface { x: number; y: number }

For plain object shapes the two are nearly interchangeable. The differences: only type can name unions, tuples, primitives, function types and computed types; interfaces can be extended with extends, are reopened by declaration merging, and give slightly nicer error messages for large object hierarchies. A common convention, and the one this course follows, is interface for object shapes that may be extended and type for everything else. Interfaces compares them in full.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Given type Euros = number; type Dollars = number;, does const d: Dollars = 5 as Euros; compile?

    An alias is only a name. Both aliases mean number, so they are fully interchangeable. Use branded types to keep them apart.
  2. 2. Which of these can ONLY be named with a type alias, not an interface?

    Interfaces describe object shapes. Unions, tuples, primitives and function types need a type alias.
  3. 3. What happens at runtime to type Theme = 'light' | 'dark';?

    Type aliases are compile-time only and vanish from the output, so they can't be used as values or checked at runtime.
  4. 4. Does type T = { a: string } & { b: number }; const t: T = { a: 'x' }; compile?

    A value of an intersection type must satisfy both sides, so it needs both a and b (TS2741).
  5. 5. Which value is NOT a valid JsonValue (the recursive type from this lesson)?

    Date is not one of the JSON members and has no string index signature, so it isn't assignable.

Summary

  • type Name = SomeType; gives any type a name: primitives, objects, unions, tuples, functions and more. Aliases compose into larger types and vanish at runtime.
  • An alias is only a name: aliases with the same structure are interchangeable. Use them for clarity and single-point changes; use branded types when you need the compiler to tell them apart.
  • Aliases are the way to name unions and function types. Generic aliases like Maybe<T> and Comparator<T> describe families of types.
  • A & B (intersection) requires the properties of both sides, a handy way to build shapes from parts.
  • Aliases can be recursive when the self-reference sits inside an object, array or function type, as in JsonValue.
  • Name types that repeat or represent domain concepts; keep small one-off shapes inline. Use interface for extendable object shapes and type for everything else.

Next: Interfaces