Codectionary / Developer documentation / TypeScript

type vs interface

Both type and interface can describe object shapes, and for that common case they are largely interchangeable. The key differences: interface supports declaration merging (multiple declarations with the same name combine automatically) and can only describe object-like shapes, while type can alias anything - unions, tuples, primitives - but cannot be re-opened once declared.

Syntax

interface Name { }
type Name = { };

Examples

Declaration Merging - interface Only

A capability unique to interfaces, often used to extend third-party library types.

interface Window {
  myCustomProperty: string;
}

interface Window {
  anotherProperty: number;
}

// TypeScript automatically merges both declarations -
// Window now has BOTH myCustomProperty and anotherProperty
// This is impossible with type - a duplicate type alias name is a compile error

What type Can Do That interface Cannot

Unions, tuples, and primitive aliases are exclusive to type.

type Status = "pending" | "active"; // interface cannot express a union like this
type Point = [number, number];       // interface cannot express a tuple like this
type ID = string | number;            // interface cannot alias a primitive union

Best practices

  • For plain object shapes, either works - many teams default to interface for public APIs and type for everything else, but consistency matters more than the specific choice
  • Use interface specifically when you need declaration merging, such as augmenting a type from a third-party library
  • Use type when you need a union, tuple, or an alias for a primitive - interface simply cannot express these
  • Within a single codebase, pick one convention for object shapes and apply it consistently, rather than mixing arbitrarily

Runtime & versions

Compiled to JavaScript. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

TypeScript Handbook

Specifications & further reading