Skip to main content

How to Extend Interfaces in TypeScript

Extending interfaces in TypeScript lets you build on existing type definitions, creating flexible and maintainable code. By adding new properties or combining multiple interfaces, you can create powerful type hierarchies without duplicating code.

In this guide, we'll explore how to extend interfaces in TypeScript through practical examples and real-world patterns. You'll learn how to add properties, combine interfaces, handle conflicts, and leverage advanced techniques like generics. Whether you're building reusable components or working with complex data structures, these patterns will help you write cleaner TypeScript code.

Adding New Properties by Extending an Interface in TypeScript​

To add new properties to an interface in TypeScript, you can use the extends keyword. Here's an example:

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

interface Admin extends User {
  role: string;
}

const admin: Admin = {
  name: 'John Doe',
  email: 'john@example.com',
  role: 'admin',
};

The Admin interface inherits all properties from User and adds its own role property. This pattern prevents code duplication while maintaining clear type relationships. When you create an object of type Admin, TypeScript ensures it includes both the inherited properties (name and email) and the new property (role).

Interface extension works with TypeScript interfaces to create modular, reusable type definitions. It's fundamental to TypeScript's type system, helping you build hierarchical structures that mirror your application's data relationships.

Organizing Code Better by Extending Interfaces in TypeScript​

You can extend interfaces in TypeScript to create a structured hierarchy, improving code organization. For example:

interface Address {
  street: string;
  city: string;
  state: string;
  zip: string;
}

interface ContactInfo {
  phone: string;
  email: string;
}

interface Customer extends Address, ContactInfo {
  name: string;
}

const customer: Customer = {
  name: 'John Doe',
  street: '123 Main St',
  city: 'Anytown',
  state: 'CA',
  zip: '12345',
  phone: '555-555-5555',
  email: 'john@example.com',
};

The Customer interface extends both Address and ContactInfo, inheriting properties from both parent interfaces. This modular approach lets you separate concerns - address information stays in one interface, contact details in another - while the Customer interface combines them without repeating property definitions.

This pattern aligns with TypeScript's approach to type composition, where you build complex types from simpler ones. It's similar to how you might structure database schemas or component hierarchies.

Combining Interfaces in TypeScript Through Extension​

To merge multiple interfaces in TypeScript, use the extends keyword with several interfaces. Here's an example:

interface Product {
  name: string;
  price: number;
}

interface Inventory {
  quantity: number;
  location: string;
}

interface StockItem extends Product, Inventory {
  supplier: string;
}

const stockItem: StockItem = {
  name: 'Widget',
  price: 19.99,
  quantity: 100,
  location: 'Warehouse A',
  supplier: 'ABC Inc.',
};

The StockItem interface combines properties from Product and Inventory by extending both. This creates a composite type containing all properties from the parent interfaces, plus any new properties defined in StockItem. TypeScript verifies that objects implementing StockItem include every required property from all extended interfaces.

This technique demonstrates how TypeScript extends enables composition over inheritance. By merging interfaces, you can create precise type definitions that reflect your domain model without duplicating type declarations across your codebase.

Extending Existing Interfaces for Custom Features​

To add custom features to an existing interface, use the extends keyword. For example:

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

interface VIPUser extends User {
  vipLevel: number;
}

const vipUser: VIPUser = {
  name: 'John Doe',
  email: 'john@example.com',
  vipLevel: 5,
};

The VIPUser interface adds a vipLevel property while preserving all properties from the base User interface. This pattern helps when you need specialized versions of existing types without modifying the original interface definition. It also maintains backward compatibility - existing code using the User interface continues to work while new code can take advantage of the extended VIPUser type.

TypeScript's interface extension works seamlessly with TypeScript types and utility types, creating flexible type hierarchies.

Keeping Type Safety When Extending Interfaces​

Ensure type safety when extending interfaces by using intersection types. For example:

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

interface Admin {
  role: string;
}

type AdminUser = User & Admin;

const adminUser: AdminUser = {
  name: 'John Doe',
  email: 'john@example.com',
  role: 'admin',
};

The AdminUser type combines User and Admin using TypeScript's intersection operator (&). While similar to interface extension, intersection types offer flexibility when working with multiple type declarations or when you can't modify the original interfaces. TypeScript verifies that objects matching the intersection type include all properties from both types.

When working with TypeScript generics, intersection types provide additional type safety for complex data structures. They're particularly useful in Convex's API generation, where type safety ensures your backend and frontend stay synchronized.

Reusing Code by Extending Interfaces​

To reuse code, create a hierarchy of interfaces and extend them as needed. For example:

interface Shape {
  area: number;
}

interface Circle extends Shape {
  radius: number;
}

interface Rectangle extends Shape {
  width: number;
  height: number;
}

const circle: Circle = {
  area: 3.14,
  radius: 5,
};

const rectangle: Rectangle = {
  area: 10,
  width: 2,
  height: 5,
};

Both Circle and Rectangle extend the Shape interface, inheriting the common area property. This pattern eliminates the need to declare shared properties repeatedly. Each specialized interface adds its own specific properties (radius for circles, width and height for rectangles) while maintaining a consistent structure through the base interface.

This inheritance pattern works well with TypeScript keyof operations and TypeScript utility types when you need to manipulate or transform these interfaces.

Managing Complex Types with Interface Extension​

Handle complex types with interface extension by using utility types like Pick<T, K> and Omit<T, K>. For example:

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

type PublicUser = Omit<User, 'password'>;

const publicUser: PublicUser = {
  name: 'John Doe',
  email: 'john@example.com',
};

The PublicUser type excludes the password property from the original User interface using TypeScript's Omit<T, K> utility type. This creates a safe subset of the interface without exposing sensitive data. TypeScript ensures you can't accidentally access the omitted property on PublicUser objects.

When building APIs with Convex's server modules, these utility types help control which properties are exposed to clients. Combining TypeScript utility types with interface extension gives you fine-grained control over your data shapes throughout your application stack.

Common Mistakes and Solutions​

When extending interfaces, you might run into name conflicts or property overwrites. Here's how to handle these issues:

interface Base {
  id: string;
  type: 'base';
}

interface Extended extends Base {
  type: 'extended'; // TypeScript error: incompatible types
}

TypeScript prevents accidental property overwrites with incompatible types. To fix this, either maintain the same type or create a new property name:

interface Extended extends Base {
  type: 'base' | 'extended'; // Compatible with base type
  extendedType: 'extended';   // Or use a different property
}

Another common issue involves circular dependencies between interfaces. When managing complex type hierarchies with TypeScript generics, split your interfaces into separate files or use type aliases to break circular references.

Practical Examples​

In real-world applications, interface extension is used to create flexible, reusable components. For example:

interface ButtonProps {
  label: string;
  onClick: () => void;
}

interface IconButtonProps extends ButtonProps {
  icon: string;
}

const iconButton: IconButtonProps = {
  label: 'Submit',
  onClick: () => console.log('Clicked'),
  icon: 'submit-icon',
};

The IconButtonProps interface extends basic button functionality by adding an icon property. This pattern shines when building component libraries - you start with a base interface defining shared behavior, then extend it for specialized components. TypeScript ensures each component receives the correct props, preventing runtime errors.

This approach integrates seamlessly with TypeScript's interface system and works well in frameworks that leverage strong typing. In Convex applications, you can apply similar patterns to define mutations, queries, and actions with type-safe parameters.

Final Thoughts on Extending Interfaces in TypeScript​

Extending interfaces in TypeScript creates reusable, maintainable code structures that grow with your application. The extends keyword and utility types form the foundation for building type hierarchies that promote code reuse and clarity.

Whether you're adding properties to existing interfaces, combining multiple interfaces, or leveraging generics for flexible types, these patterns help you write better TypeScript code. In production applications like those built with Convex, interface extension ensures type safety across your entire stack - from database schemas to API endpoints to frontend components.