Interfaces in TypeScript: Describing the Shape of Your Objects

Most of the data you work with in real programs isn’t a single number or word. It’s an object: a customer with a name and an email, a product with a price and a label, a settings record with a handful of flags. The moment your code starts passing these objects around, you want a way to say “this thing should look like this.” That description is exactly what an interface gives you.

In TypeScript, an interface is a named blueprint for the shape of an object. It lists which properties the object has and what type each one should be. You write the blueprint once, attach it wherever you need it, and TypeScript quietly checks that every object actually matches. It’s the everyday workhorse for typing objects, and once it clicks you’ll reach for it constantly.

What “the shape of an object” means

Before any TypeScript, let’s be precise about the word shape. When we talk about the shape of an object, we mean two things together: the names of its properties and the type of value stored under each name.

Take a plain object like this:

const user = {
  name: "John Doe",
  email: "john@example.com",
  age: 34,
};

Its shape is: a name that is a string, an email that is a string, and an age that is a number. An interface is just a way to write that down as a reusable rule, with a name you can refer to later.

Defining your first interface

You declare an interface with the interface keyword, a name, and a block listing each property and its type. By convention the name starts with a capital letter, like User.

interface User {
  name: string;
  email: string;
  age: number;
}

Read it out loud: “A User has a name that is a string, an email that is a string, and an age that is a number.” Notice there are no values here, only types. An interface is a contract, not actual data. It describes what a User must look like without being a User itself.

A small but common point of confusion: you can separate the properties with semicolons, commas, or just newlines. All three work. Pick one and stay consistent. Most people use newlines (or semicolons) inside interfaces.

Using an interface

A blueprint is only useful once you attach it to something. The most common place is when you declare a variable or a function parameter. You annotate it with a colon followed by the interface name.

interface User {
  name: string;
  email: string;
  age: number;
}

const john: User = {
  name: "John Doe",
  email: "john@example.com",
  age: 34,
};

Now TypeScript holds john to the User contract. If you forget a required property, misspell one, or give it the wrong type, you get an error before the code ever runs:

const broken: User = {
  name: "Jane Doe",
  email: "jane@example.com",
  // age is missing -> TypeScript complains here
};

The same blueprint shines in function parameters. Instead of repeating the property list everywhere, you name the interface once and reuse it:

interface User {
  name: string;
  email: string;
  age: number;
}

function greet(person: User): string {
  return `Hello, ${person.name}!`;
}

greet({ name: "John Doe", email: "john@example.com", age: 34 });

Inside greet, TypeScript knows person has a name, an email, and an age. You get autocomplete for them, and a typo like person.naem is caught instantly. That editor help is half the reason interfaces feel so good to use.

Optional properties with ?

Not every property is always present. Maybe most users have a phone number, but some don’t. You don’t want to force a value that isn’t there, and you also don’t want to drop type safety. The answer is the optional marker: a question mark after the property name.

interface User {
  name: string;
  email: string;
  age: number;
  phone?: string;
}

The phone? means “a User may have a phone, and if it does, it’s a string.” Both of these objects are now valid:

const withPhone: User = {
  name: "John Doe",
  email: "john@example.com",
  age: 34,
  phone: "+62 812 0000 0000",
};

const withoutPhone: User = {
  name: "Jane Doe",
  email: "jane@example.com",
  age: 29,
};

There’s a catch worth knowing early. When you read an optional property, its type is “the value or undefined,” because it might be missing. So TypeScript will nudge you to check before using it:

function callUser(user: User) {
  // user.phone might be undefined, so guard it first
  if (user.phone) {
    console.log(`Calling ${user.phone}`);
  } else {
    console.log("No phone on file");
  }
}

That little check isn’t busywork. It’s TypeScript reminding you of a real case your code would otherwise forget to handle.

Read-only properties with readonly

Some values should be set once and never change. An id assigned when a record is created is the classic example. You can mark a property as readonly so that any later attempt to reassign it becomes an error.

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

const john: User = {
  id: 101,
  name: "John Doe",
  email: "john@example.com",
};

john.name = "John A. Doe"; // fine, name is mutable
john.id = 999;             // error: id is readonly

You can still read a readonly property as much as you like. You just can’t assign to it after the object is created. Think of it as a guardrail: it documents your intent (“this never changes”) and lets the compiler enforce it for you.

Extending interfaces

As an app grows, you’ll often find one shape that’s a more specific version of another. An admin is a user with extra powers. A premium product is a product with a discount field. Rewriting every shared property each time would be tedious and error-prone. Interfaces solve this with extends.

extends lets one interface build on top of another, inheriting all of its properties and adding its own:

interface User {
  name: string;
  email: string;
}

interface Admin extends User {
  role: "admin";
  canDeleteUsers: boolean;
}

An Admin now requires everything a User requires (name, email) plus its own two properties. You only wrote the shared fields once:

const boss: Admin = {
  name: "Jane Doe",
  email: "jane@example.com",
  role: "admin",
  canDeleteUsers: true,
};

You can extend from more than one interface at a time by separating them with commas, which is handy when a shape combines several smaller ones:

interface Timestamped {
  createdAt: string;
  updatedAt: string;
}

interface Account extends User, Timestamped {
  plan: "free" | "pro";
}

Here, an Account carries the user fields, the timestamp fields, and its own plan. This kind of composition keeps each interface small and focused while letting you assemble bigger shapes from the pieces.

   User                 Timestamped
  ┌──────────┐         ┌────────────┐
  │ name     │         │ createdAt  │
  │ email    │         │ updatedAt  │
  └────┬─────┘         └─────┬──────┘
       │                     │
       └────────┬────────────┘
                ▼
            Account
       ┌─────────────────┐
       │ name, email     │
       │ createdAt,      │
       │ updatedAt       │
       │ plan            │
       └─────────────────┘

A quick reference for the syntax

Here’s everything in one table so you can scan it later:

Recap

Interfaces are how you give a name to the shape of an object and let TypeScript hold your code to it. Here’s the short version of everything above:

• An interface lists an object’s properties and their types. It’s a compile-time contract that disappears when the code runs.
• Attach it with a colon (const john: User = ... or function greet(person: User)) to get checking and editor autocomplete.
• Add ? for optional properties; remember the value might be undefined, so guard before using it.
• Add readonly for properties that should be set once and never reassigned (the protection is shallow).
• Use extends to build a more specific interface on top of an existing one, even combining several at once.

Start by giving names to the objects you already pass around in your code. Each interface you write makes the next change safer, because TypeScript now knows what your data is supposed to look like and will speak up the moment something drifts out of shape.