TypeScript Interface: Syntax, Optional, Methods and Examples

An interface gives a name to the shape of an object: the properties it must have and the type of each. Once declared, you use the name as a type, and the compiler checks every object you pass, return or assign against it.

interface User {
  id: number;
  name: string;
  email?: string; // optional
}

function describe(user: User): string {
  return `#${user.id} ${user.name} <${user.email ?? "no email"}>`;
}

const ada: User = { id: 1, name: "Ada Lovelace", email: "ada@example.com" };

console.log(describe(ada));                       // #1 Ada Lovelace <ada@example.com>
console.log(describe({ id: 2, name: "Alan Turing" })); // #2 Alan Turing <no email>

// @ts-expect-error: Property 'name' is missing in type '{ id: number; }' but required in type 'User'.
describe({ id: 3 });

The last call is compile error TS2741. Interfaces are erased when the code is compiled: the JavaScript output has no trace of User, and nothing checks the shape at runtime.

Declaring an Interface

The syntax is the keyword interface, a name (PascalCase by convention), and a body listing members. Members can be separated by semicolons, commas or just line breaks; semicolons are the common style.

interface Product {
  sku: string;               // required property
  price: number;
  tags: string[];            // array property
  dimensions: {              // nested object type
    width: number;
    height: number;
  };
  discount?: number;         // optional property
  readonly createdAt: Date;  // cannot be reassigned
  label(): string;           // method
}

An interface is a type, not a value. It cannot be instantiated with new, it has no default values, and obj instanceof Product is error TS2693 ('Product' only refers to a type, but is being used as a value here). To check a shape at runtime, write a type guard.

Structural Typing and Excess Property Checks

TypeScript compares shapes, not names. Any object with the required properties fits the interface, whether or not it was declared with it. Extra properties are fine, with one exception: an object literal written directly where the interface is expected gets an excess property check, because an unknown key there is almost always a typo.

interface Point {
  x: number;
  y: number;
}

function distance(p: Point): number {
  return Math.hypot(p.x, p.y);
}

const saved = { x: 3, y: 4, label: "A" }; // never declared as a Point
console.log(distance(saved));             // 5: the shape matches

// @ts-expect-error: Object literal may only specify known properties, and 'label' does not exist in type 'Point'.
distance({ x: 3, y: 4, label: "A" });

That error (TS2353) is what catches { id: 1, name: "a", emial: "x" } for a User: the compiler even suggests Did you mean to write 'email'? (TS2561).

Optional and Readonly Properties

A ? after the name makes a property optional: the object may leave it out, and reading it gives T | undefined. readonly forbids reassigning the property after the object is created.

interface Config {
  readonly apiUrl: string;
  readonly hosts: readonly string[];
  timeoutMs?: number;
}

const config: Config = { apiUrl: "https://api.example.com", hosts: ["a", "b"] };

// @ts-expect-error: Cannot assign to 'apiUrl' because it is a read-only property.
config.apiUrl = "http://localhost";
// @ts-expect-error: Property 'push' does not exist on type 'readonly string[]'.
config.hosts.push("c");

console.log(config.timeoutMs ?? 5000); // 5000: optional, so check or default it

const local = { ...config, apiUrl: "http://localhost" }; // a changed copy is fine
console.log(local.apiUrl); // http://localhost

// readonly is a compile-time rule attached to this type only:
const writable: { apiUrl: string } = config; // allowed
writable.apiUrl = "changed";
console.log(config.apiUrl); // changed

Two limits show here. First, readonly is compile-time only: the two lines marked @ts-expect-error still run when you press Run, and they succeed, and the last lines change apiUrl through a reference typed without readonly. Second, it is shallow: readonly hosts: string[] would stop reassigning hosts but still allow hosts.push(...), which is why the array itself is typed readonly string[]. It documents and enforces intent in typed code; it does not freeze anything. The Readonly<T> utility type makes every property of an existing interface readonly at once.

Methods and Function Properties

A method can be written as a method signature, name(params): ReturnType, or as a property holding a function, name: (params) => ReturnType. Callers use both the same way.

interface Counter {
  count: number;
  increment(by?: number): void; // method signature
  reset: () => void;            // property holding a function
}

function createCounter(): Counter {
  return {
    count: 0,
    increment(by = 1) {
      this.count += by; // this is typed as Counter
    },
    reset() {
      this.count = 0;
    },
  };
}

const c = createCounter();
c.increment();
c.increment(5);
console.log(c.count); // 6
c.reset();
console.log(c.count); // 0

The difference is subtle: under strictFunctionTypes (part of strict), parameters of function-typed properties are checked strictly, while method signatures are checked more loosely (bivariantly), so the property form catches a few more mistakes. Method syntax is shorter and the more common style; both are fine.

An interface can also describe something callable or constructible, using a call signature or a construct signature:

interface Formatter {
  (value: number): string; // call signature: the object is a function
  locale: string;          // and it also has a property
}

interface PointConstructor {
  new (x: number, y: number): { x: number; y: number }; // construct signature
}

Index Signatures

When the property names are not known in advance, an index signature describes all of them at once: [key: string]: T means "any string key, each holding a T".

interface Scores {
  [player: string]: number;
}

const scores: Scores = { ada: 90, alan: 85 };
scores.grace = 95; // any string key is allowed
scores["linus"] = 70;

for (const [player, score] of Object.entries(scores)) {
  console.log(player, score);
}

const missing = scores.nobody; // typed number, actually undefined
console.log(missing);          // undefined

The last lines show the catch: reading a key that does not exist is typed as number, not number | undefined. The compiler option noUncheckedIndexedAccess adds | undefined to every such read.

Named properties can sit next to an index signature, but they must fit it. interface Dict { [key: string]: number; name: string } is error TS2411, Property 'name' of type 'string' is not assignable to 'string' index type 'number'. Widen the index type ([key: string]: number | string) or move the dynamic part into its own property. For simple key/value maps, Record<string, number> says the same thing in one line.

Extending an Interface

extends builds a new interface from one or more existing ones. The child has every parent member plus its own:

interface Animal {
  name: string;
}

interface Pet extends Animal {
  owner: string;
}

interface Trained {
  commands: string[];
}

interface ServiceDog extends Pet, Trained {
  certifiedUntil: Date;
}

// ServiceDog requires: name, owner, commands, certifiedUntil

A child may redeclare a parent property only with a compatible (narrower) type, such as kind: "dog" where the parent says kind: string. The rules, and how to extend type aliases, are on the extends page.

Implementing an Interface in a Class

class X implements Shape asks the compiler to check that the class has everything the interface requires. A missing member is an error at the class declaration:

// This does not compile: Circle is missing area()
interface Shape {
  name: string;
  area(): number;
}

class Circle implements Shape {
  name = "circle";
  constructor(public radius: number) {}
}

console.log(new Circle(2).name);

index.ts(7,7): error TS2420: Class 'Circle' incorrectly implements interface 'Shape'.
  Property 'area' is missing in type 'Circle' but required in type 'Shape'.

With area() added, several classes and even a plain object can all be used as a Shape:

interface Shape {
  name: string;
  area(): number;
}

class Circle implements Shape {
  name = "circle";
  constructor(public radius: number) {}
  area() {
    return Math.PI * this.radius ** 2;
  }
}

class Rect implements Shape {
  name = "rect";
  constructor(public w: number, public h: number) {}
  area() {
    return this.w * this.h;
  }
}

// A plain object with the right shape is a Shape too: no class needed.
const unitSquare: Shape = { name: "unit square", area: () => 1 };

const shapes: Shape[] = [new Circle(1), new Rect(2, 3), unitSquare];
for (const s of shapes) {
  console.log(s.name, s.area().toFixed(2));
}

implements is only a check. It does not add members to the class, and it does not type the class's method parameters for you: greet(name) {} inside a class that implements greet(name: string): string is still error TS7006, Parameter 'name' implicitly has an 'any' type. A class can implement several interfaces: class A implements B, C.

Declaration Merging

Declaring an interface with the same name twice in the same scope merges the two into one. This is something type aliases cannot do (a second type with the same name is a duplicate identifier error).

interface Settings {
  theme: string;
}

interface Settings {
  fontSize: number;
}

// Settings now requires both properties
const s: Settings = { theme: "dark", fontSize: 14 };

In application code this is rarely what you want, and an accidental merge can be confusing. Its real use is adding members to types you do not own: a library's options, or a global such as Window. From inside a module, wrap the declaration in declare global:

declare global {
  interface Window {
    analytics: { track(event: string): void };
  }
}

export {};

After this, window.analytics.track("signup") type-checks everywhere in the project. Type definition packages rely on the same mechanism; see declaration files.

Default Values for Interface Properties

An interface cannot hold default values, because it describes types and is erased at runtime. size?: "sm" | "md" = "md" is error TS1246, An interface property cannot have an initializer. Make the property optional and fill in the default where the object is used:

interface ButtonOptions {
  label: string;
  size?: "sm" | "md" | "lg";
  disabled?: boolean;
}

// 1. Destructuring defaults: applied when the value is undefined
function render({ label, size = "md", disabled = false }: ButtonOptions): string {
  return `[${label}] size=${size} disabled=${disabled}`;
}

// 2. Spread a defaults object under the options
const DEFAULTS = { size: "md", disabled: false } as const;

function withDefaults(options: ButtonOptions) {
  return { ...DEFAULTS, ...options };
}

console.log(render({ label: "Save" }));                   // [Save] size=md disabled=false
console.log(render({ label: "Save", size: undefined }));  // [Save] size=md disabled=false
console.log(withDefaults({ label: "Save", size: "lg" }));  // { size: 'lg', disabled: false, label: 'Save' }
console.log(withDefaults({ label: "Save", size: undefined }));
// { size: undefined, disabled: false, label: 'Save' }

Destructuring defaults are the safer choice: they apply whenever the value is undefined, including an explicit size: undefined. The spread version copies that explicit undefined over the default, and its result is still typed as if size were always set. If you need that guarantee from the types, turn on exactOptionalPropertyTypes, which makes size: undefined a compile error for an optional size?: .... A class with initialized fields is the other option when the object needs behavior too.

Generic Interfaces

An interface can take type parameters, which makes one declaration work for many payload types:

interface ApiResponse<T> {
  ok: boolean;
  data: T;
  error?: string;
}

interface Page<T> {
  items: T[];
  nextCursor?: string;
}

interface User {
  id: number;
  name: string;
}

const res: ApiResponse<Page<User>> = {
  ok: true,
  data: { items: [{ id: 1, name: "Ada" }], nextCursor: "abc" },
};

ApiResponse<Page<User>> reads as "a response whose data is a page of users". The standard library is full of these: Array<T>, Promise<T>, Map<K, V> are all generic interfaces.

Interface vs Type Alias

A type alias can describe the same object shape, and for plain object types the two are interchangeable. Only an interface can merge; only a type alias can name a union, a tuple, or a mapped or conditional type. The TypeScript handbook's rule of thumb is to use interface until you need a feature that only type has. The interface vs type page has the full comparison, including the Record<string, ...> difference that surprises most people.