TypeScript Type Alias: The type Keyword with Examples

A type alias gives a name to a type. You write type Name = ..., and from then on Name can be used anywhere a type is expected. Unlike an interface, an alias can name any type at all, not only object shapes.

type UserId = string;                         // a primitive
type Point = { x: number; y: number };        // an object shape
type Status = "active" | "banned";            // a union of literals
type Pair = [string, number];                 // a tuple
type Formatter = (value: number) => string;   // a function

const id: UserId = "u_42";
const start: Point = { x: 0, y: 0 };
const current: Status = "active";
const entry: Pair = ["score", 90];
const money: Formatter = (v) => `$${v.toFixed(2)}`;

console.log(id, start, current, entry, money(3.5));
// u_42 { x: 0, y: 0 } active [ 'score', 90 ] $3.50

Aliases exist only at compile time. The emitted JavaScript contains none of these type lines.

Syntax

type Name = SomeType;
type Name<T> = SomeTypeUsing<T>;       // generic
export type Name = SomeType;           // exported from a module

Names are PascalCase by convention. The right-hand side is any type expression, and an alias can use other aliases, including itself (see recursive types below). The alias is available in the whole scope where it is declared, even above the declaration line, because types are checked at compile time and not executed in order like const or let.

Object Types

For an object shape, an alias and an interface are written almost the same way. The alias uses = and is usually ended with a semicolon.

type User = {
  id: number;
  name: string;
  email?: string;           // optional
  readonly createdAt: string; // cannot be reassigned
};

type Admin = User & { permissions: string[] }; // extend with an intersection

const root: Admin = {
  id: 1,
  name: "root",
  createdAt: "2024-03-15",
  permissions: ["*"],
};

console.log(`${root.name} can do ${root.permissions.join(", ")}`); // root can do *

An alias cannot use extends; the & intersection plays that role. Excess property checks, optional and readonly properties work exactly as they do for interfaces. Which of the two to pick for object shapes is covered on the interface vs type page.

Unions, Tuples and Functions

These are the cases only an alias can name, and the main reason type exists. A union alias lists the alternatives, a tuple alias fixes the length and element types of an array, and a function alias describes a signature.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

type Span = [start: number, end: number]; // labeled tuple elements

type Transform = (shape: Shape, factor: number) => Shape;

const scale: Transform = (shape, factor) =>
  shape.kind === "circle"
    ? { kind: "circle", radius: shape.radius * factor }
    : { kind: "rect", width: shape.width * factor, height: shape.height * factor };

const r: Span = [10, 20];
console.log(scale({ kind: "circle", radius: 2 }, 3)); // { kind: 'circle', radius: 6 }
console.log(r[1] - r[0]);                              // 10

In scale, the parameters need no annotations: the Transform alias supplies their types. Tuple syntax is covered in tuples, and union narrowing in the union types page.

Generic Type Aliases

Type parameters make one alias work for many types. They can have defaults, just like function parameters.

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0
    ? { ok: true, value: n }
    : { ok: false, error: `not an age: ${text}` };
}

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? `age ${r.value}` : r.error);
}
// age 36
// not an age: abc

Result<number> uses the default E = string. Small generic aliases like type Nullable<T> = T | null or type Dict<T> = Record<string, T> are common in real code. The built-in utility types (Partial<T>, Pick<T, K>, ReturnType<F>) are generic aliases too, declared in the standard library.

Aliases Are Names, Not New Types

An alias does not create a distinct type. It is a second name for the type on the right, and the compiler treats the two as identical. Two aliases of string are fully interchangeable:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: UserId and OrderId are both just string

This prints cancelling u_42 with no error, which is the bug an alias cannot prevent. The alias still helps readers (a parameter typed OrderId says more than string), but if mixing up two ids must be a compile error, use a branded type such as string & { readonly __brand: "OrderId" }.

Recursive Type Aliases

An alias can refer to itself, which is how you describe trees, nested lists and JSON:

type Json =
  | string
  | number
  | boolean
  | null
  | Json[]
  | { [key: string]: Json };

type TreeNode = {
  value: number;
  children: TreeNode[];
};

function sum(node: TreeNode): number {
  return node.value + node.children.reduce((total, child) => total + sum(child), 0);
}

const tree: TreeNode = {
  value: 1,
  children: [
    { value: 2, children: [] },
    { value: 3, children: [{ value: 4, children: [] }] },
  ],
};

const payload: Json = { ok: true, items: [1, "two", null], meta: { page: 1 } };

console.log(sum(tree));               // 10
console.log(JSON.stringify(payload)); // {"ok":true,"items":[1,"two",null],"meta":{"page":1}}

The Json alias rejects values that JSON cannot represent: { when: new Date() } or { f: undefined } assigned to Json are compile errors (TS2322).

Types from Values: typeof

When a value already exists, you can name its type instead of writing it out. The typeof type operator reads the type of a variable, and it combines with other operators:

const defaults = { retries: 3, verbose: false, level: "info" };

type Options = typeof defaults;
// { retries: number; verbose: boolean; level: string }

type OptionKey = keyof typeof defaults;
// "retries" | "verbose" | "level"

function start(port: number) {
  return { port, startedAt: new Date() };
}
type Server = ReturnType<typeof start>;
// { port: number; startedAt: Date }

The value stays the single source of truth: add a property to defaults and Options follows. More on this in typeof.

Exporting and Importing Aliases

Aliases are exported and imported like values. import type makes it explicit that only a type is imported, so the import is always removed from the JavaScript output:

// shapes.ts
export type Point = { x: number; y: number };
export type Shape = { kind: "circle"; center: Point; radius: number };

// main.ts
import type { Point, Shape } from "./shapes.js";

const p: Point = { x: 1, y: 2 };