TypeScript Interfaces: Comprehensive Guide

// Basic interface declaration
interface User {
  name: string;
  age: number;
  email: string;
}

// Using the interface
const user: User = {
  name: "Alice",
  age: 30,
  email: "alice@example.com"
};

// TypeScript enforces the interface
const invalidUser: User = {
  name: "Bob",
  // age: 25, // Error: Property 'age' is missing
  email: "bob@example.com"
};

// Interface for function parameters
function greetUser(user: User) {
  console.log(`Hello, ${user.name}!`);
}

greetUser(user); // ✅ Valid
greetUser({ name: "Charlie" }); // ❌ Error: Missing age and email

// Interface for return types
function createUser(name: string, age: number, email: string): User {
  return {
    name,
    age,
    email
  };
}

// Interface for React component props
interface ButtonProps {
  label: string;
  onClick: () => void;
  disabled?: boolean;
}

function Button({ label, onClick, disabled = false }: ButtonProps) {
  return (
    <button onClick={onClick} disabled={disabled}>
      {label}
    </button>
  );
}

Interfaces define object shapes. Use them for props, function parameters, return types, and any object structure. TypeScript enforces interface contracts at compile time.

// Optional properties
interface UserProfile {
  name: string;
  age: number;
  email?: string; // Optional - may or may not be present
  phone?: string; // Optional
  bio?: string; // Optional
}

const user1: UserProfile = {
  name: "Alice",
  age: 30,
  email: "alice@example.com"
  // phone and bio are optional, so we can omit them
};

const user2: UserProfile = {
  name: "Bob",
  age: 25
  // All optional properties omitted
};

// Readonly properties
interface Config {
  readonly apiUrl: string;
  readonly timeout: number;
  environment: string; // Not readonly, can be changed
}

const config: Config = {
  apiUrl: "https://api.example.com",
  timeout: 5000,
  environment: "production"
};

config.apiUrl = "https://other.com"; // ❌ Error: Cannot assign to 'apiUrl' because it is a read-only property
config.environment = "development"; // ✅ OK - not readonly

// Combining optional and readonly
interface Settings {
  readonly theme: string;
  readonly language?: string; // Optional AND readonly
  notifications: boolean;
}

const settings: Settings = {
  theme: "dark",
  notifications: true
  // language is optional, so we can omit it
};

settings.theme = "light"; // ❌ Error: readonly
settings.language = "en"; // ❌ Error: readonly (if it exists)
settings.notifications = false; // ✅ OK

// React component with optional props
interface CardProps {
  title: string;
  description?: string; // Optional
  readonly id: string; // Readonly - cannot be changed
  onClick?: () => void; // Optional function
}

function Card({ title, description, id, onClick }: CardProps) {
  // id is readonly, so we can read it but not modify it
  return (
    <div onClick={onClick} data-id={id}>
      <h2>{title}</h2>
      {description && <p>{description}</p>}
    </div>
  );
}

Use ? for optional properties that may be omitted. Use readonly for properties that shouldn't change after initialization. Combine both when needed for immutable optional properties.

// Basic interface extension
interface Animal {
  name: string;
  age: number;
}

interface Dog extends Animal {
  breed: string;
  bark: () => void;
}

const myDog: Dog = {
  name: "Buddy",
  age: 3,
  breed: "Golden Retriever",
  bark: () => console.log("Woof!")
};

// Multiple interface extension
interface Flyable {
  fly: () => void;
}

interface Swimmable {
  swim: () => void;
}

interface Duck extends Animal, Flyable, Swimmable {
  quack: () => void;
}

const myDuck: Duck = {
  name: "Donald",
  age: 2,
  fly: () => console.log("Flying"),
  swim: () => console.log("Swimming"),
  quack: () => console.log("Quack!")
};

// React component prop hierarchies
interface BaseButtonProps {
  disabled?: boolean;
  className?: string;
}

interface PrimaryButtonProps extends BaseButtonProps {
  variant: "primary";
  onClick: () => void;
}

interface SecondaryButtonProps extends BaseButtonProps {
  variant: "secondary";
  onClick?: () => void;
}

// Using extended interfaces
function Button(props: PrimaryButtonProps | SecondaryButtonProps) {
  return (
    <button
      className={props.className}
      disabled={props.disabled}
      onClick={props.onClick}
    >
      {props.variant}
    </button>
  );
}

// Extending with additional properties
interface User {
  id: string;
  name: string;
  email: string;
}

interface AdminUser extends User {
  permissions: string[];
  role: "admin";
}

interface RegularUser extends User {
  role: "user";
  subscription?: string;
}

// Conditional types with extended interfaces
function getUserDisplay(user: AdminUser | RegularUser) {
  if (user.role === "admin") {
    // TypeScript knows this is AdminUser
    console.log(`Admin: ${user.name} with ${user.permissions.length} permissions`);
  } else {
    // TypeScript knows this is RegularUser
    console.log(`User: ${user.name}`);
  }
}

Extend interfaces using the extends keyword. Interfaces can extend multiple interfaces. Use extension to build type hierarchies and reuse common properties. This is especially useful for React component prop types.

// String index signature
interface StringDictionary {
  [key: string]: string;
}

const colors: StringDictionary = {
  red: "#ff0000",
  blue: "#0000ff",
  green: "#00ff00"
  // Can add any string key
};

colors.yellow = "#ffff00"; // ✅ OK
colors["purple"] = "#800080"; // ✅ OK

// Number index signature
interface NumberDictionary {
  [index: number]: string;
}

const items: NumberDictionary = {
  0: "first",
  1: "second",
  2: "third"
};

// Combining known properties with index signature
interface UserPreferences {
  theme: string; // Known property
  language: string; // Known property
  [key: string]: string | number; // Index signature - allows any other string key
}

const prefs: UserPreferences = {
  theme: "dark",
  language: "en",
  fontSize: 14, // ✅ OK - matches index signature
  customSetting: "value" // ✅ OK
};

// React component with dynamic props
interface FlexibleComponentProps {
  title: string; // Required known property
  [propName: string]: string | number | boolean | undefined; // Dynamic props
}

function FlexibleComponent({ title, ...rest }: FlexibleComponentProps) {
  return (
    <div>
      <h2>{title}</h2>
      {Object.entries(rest).map(([key, value]) => (
        <div key={key}>
          {key}: {String(value)}
        </div>
      ))}
    </div>
  );
}

// API response with dynamic properties
interface ApiResponse {
  status: number;
  message: string;
  [key: string]: unknown; // Can have any additional properties
}

function handleResponse(response: ApiResponse) {
  console.log(response.status);
  console.log(response.message);
  // Can access any other properties
  if ('data' in response) {
    console.log(response.data);
  }
}

// Dictionary with typed values
interface Cache<T> {
  [key: string]: T;
}

const stringCache: Cache<string> = {
  user1: "Alice,
  user2: "Bob"
};

const numberCache: Cache<number> = {
  count1: 10,
  count2: 20
};

Index signatures allow dynamic property names. Use string index signatures for dictionaries and objects with unknown keys. Combine with known properties for flexible but type-safe interfaces.

// Interface merging - same name, different declarations
interface User {
  name: string;
  age: number;
}

interface User {
  email: string; // Merged with previous declaration
}

// Result: User has name, age, and email
const user: User = {
  name: "Alice",
  age: 30,
  email: "alice@example.com"
};

// Merging across files
// file1.ts
interface Config {
  apiUrl: string;
}

// file2.ts
interface Config {
  timeout: number; // Merged with file1's Config
}

// Result: Config has both apiUrl and timeout

// Extending library types (module augmentation)
// Extending Window interface
interface Window {
  myCustomProperty: string;
  myCustomMethod: () => void;
}

// Now you can use
window.myCustomProperty = "value";
window.myCustomMethod();

// Extending React types
declare module 'react' {
  interface HTMLAttributes<T> {
    customAttr?: string;
  }
}

// Now all HTML elements can have customAttr
<div customAttr="value">Content</div>

// Merging with method overloads
interface Calculator {
  add(a: number, b: number): number;
}

interface Calculator {
  add(a: string, b: string): string; // Method overload
}

// Result: Calculator.add can accept numbers or strings

// Merging with different property types (causes error)
interface Conflicting {
  value: string;
}

interface Conflicting {
  value: number; // ❌ Error: Property 'value' of type 'number' is not assignable to type 'string'
}

// Merging with compatible types
interface Compatible {
  value: string | number; // Union type allows both
}

interface Compatible {
  value: string | number | boolean; // ✅ OK - extends the union
}

Interface merging combines multiple declarations of the same interface. Use it to extend third-party types, add global properties, and build interfaces incrementally. Be careful with type conflicts.

// Function type in interface
interface SearchFunction {
  (query: string): string[];
}

const search: SearchFunction = (query) => {
  return [`Result for ${query}`];
};

// Interface with both properties and function
interface Calculator {
  value: number;
  add: (a: number, b: number) => number;
  subtract(a: number, b: number): number; // Method signature syntax
}

const calc: Calculator = {
  value: 0,
  add: (a, b) => a + b,
  subtract: (a, b) => a - b
};

// Function with multiple call signatures (overloads)
interface StringOrNumberProcessor {
  (value: string): string;
  (value: number): number;
}

// Implementing the overloaded function
const process: StringOrNumberProcessor = (value: string | number) => {
  if (typeof value === "string") {
    return value.toUpperCase();
  }
  return value * 2;
};

// React event handler types
interface ButtonProps {
  onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
  onHover?: (event: React.MouseEvent<HTMLButtonElement>) => void;
  children: React.ReactNode;
}

function Button({ onClick, onHover, children }: ButtonProps) {
  return (
    <button onClick={onClick} onMouseEnter={onHover}>
      {children}
    </button>
  );
}

// Callback interface
interface DataFetcher {
  fetch: (url: string) => Promise<unknown>;
  onSuccess: (data: unknown) => void;
  onError: (error: Error) => void;
}

// Generic function interface
interface Transformer<T, U> {
  (input: T): U;
}

const stringToNumber: Transformer<string, number> = (str) => 
  parseInt(str, 10);

const numberToString: Transformer<number, string> = (num) => 
  String(num);

// Interface with constructor signature
interface UserConstructor {
  new (name: string, age: number): User;
}

class User {
  constructor(public name: string, public age: number) {}
}

function createUser(ctor: UserConstructor, name: string, age: number) {
  return new ctor(name, age);
}

const user = createUser(User, "Alice", 30);

Interfaces can describe function shapes using call signatures. Use them for typing functions, callbacks, event handlers, and methods. Support multiple overloads for flexible function types.

// ✅ GOOD: Descriptive, focused interface
interface UserProfile {
  id: string;
  name: string;
  email: string;
  avatarUrl?: string;
}

// ✅ GOOD: Props interface with clear naming
interface UserCardProps {
  user: UserProfile;
  onEdit?: (user: UserProfile) => void;
  showActions?: boolean;
}

// ✅ GOOD: Grouped related interfaces
// types/user.ts
export interface User {
  id: string;
  name: string;
  email: string;
}

export interface UserPreferences {
  userId: string;
  theme: "light" | "dark";
  language: string;
}

export interface UserWithPreferences extends User {
  preferences: UserPreferences;
}

// ✅ GOOD: Generic interface for reusability
interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
}

interface UserResponse extends ApiResponse<User> {}
interface ProductResponse extends ApiResponse<Product> {}

// ✅ GOOD: Documented interface
/**
 * Represents a user in the system
 * @property id - Unique identifier
 * @property name - User's full name
 * @property email - User's email address
 * @property role - User's role in the system
 */
interface User {
  /** Unique identifier */
  id: string;
  /** User's full name */
  name: string;
  /** User's email address */
  email: string;
  /** User's role */
  role: "admin" | "user" | "guest";
}

// ✅ GOOD: Readonly for immutability
interface Config {
  readonly apiUrl: string;
  readonly version: string;
  environment: string; // Can be changed
}

// ❌ BAD: Too broad, unclear purpose
interface Data {
  // What kind of data? Too vague
}

// ❌ BAD: Deep nesting
interface BadStructure {
  user: {
    profile: {
      settings: {
        theme: string; // Too nested
      };
    };
  };
}

// ✅ GOOD: Flattened structure
interface UserSettings {
  theme: string;
}

interface UserProfile {
  settings: UserSettings;
}

interface User {
  profile: UserProfile;
}

Follow best practices: use descriptive names, keep interfaces focused, prefer interfaces for object shapes, use readonly for immutability, document complex interfaces, and organize related interfaces together.