Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Keywords and Declarations

TypeScript interface

Reference for the TypeScript interface keyword: object shapes, optional and readonly members, call signatures, extends, declaration merging and interface versus type.

An interface declares the shape of an object: which properties it has, their types, and which methods it offers. Interfaces are purely a compile-time construct. They are erased from the JavaScript output.

Interfaces can extend other interfaces, can be implemented by classes, and, uniquely, can be declared several times with the same name so the declarations merge into one. That last feature makes them the right tool for augmenting types from libraries.

TypeScript
interface User {
  readonly id: number;
  name: string;
  email?: string;
  greet(): string;
}

Try it

TypeScript Shapes, optional and readonly members

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.

TypeScript extends and declaration merging

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.

Syntax

TypeScript
interface Name<T = Default> extends Base1, Base2 {
  prop: Type;
  optional?: Type;
  readonly fixed: Type;
  method(arg: Type): Return;
  arrow: (arg: Type) => Return;
  [key: string]: Type;          // index signature
  (arg: Type): Return;          // call signature
  new (arg: Type): Instance;    // construct signature
  get size(): number;           // accessor (TypeScript 4.3+)
}
Part Description
Name The interface name. Several declarations with the same name merge.
<T> Optional type parameters with constraints and defaults.
extends One or more interfaces (or object type aliases) whose members are inherited.
Members Properties, methods, index signatures, call and construct signatures.

Errors and edge cases:

  • An extending interface cannot make an inherited property incompatible with the base (error TS2430, "Interface 'Dog' incorrectly extends interface 'Animal'").
  • Merged declarations must repeat non-function properties with identical types; otherwise TS2717 ("Subsequent property declarations must have the same type").
  • Object literals are checked for excess properties: an unknown property in a fresh literal assigned to an interface type is error TS2353.
  • Method members are compared bivariantly under strictFunctionTypes, while property members declared with arrow types are checked contravariantly.

Usage notes

  • Merging. Same-named interfaces in the same scope combine; later declarations take priority for overloads. This is how you add fields to Window or to Express.Request.
  • extends is checked early. Conflicts are reported at the interface, which makes errors easier to read than intersection types.
  • Classes can implement interfaces with implements, and an interface can extend a class, inheriting its members (including private ones, which then restricts implementers to subclasses).
  • Interfaces versus aliases. Interfaces cannot name unions, tuples or primitives. An alias cannot merge. For plain object shapes either works.
  • No implicit index signature. An interface type is not assignable to Record<string, unknown> unless it declares an index signature, while an equivalent type alias is.
  • Optional is not undefined-only. email?: string means the property may be missing; with exactOptionalPropertyTypes it cannot be explicitly set to undefined.
  • Nothing exists at run time. You cannot test x instanceof User; use a type guard.