Structural

Composite

Compose objects into tree structures to represent part-whole hierarchies, letting clients treat individual objects and compositions uniformly.

Intent

Let clients work with complex tree structures by treating both leaf nodes and branches through the same interface, so that adding, removing, or operating on elements does not require the client to distinguish between simple and compound objects.

Problem

Your domain has a natural part-whole hierarchy -- files and directories, departments and employees, or UI containers and widgets. Client code that traverses or operates on this structure is littered with type checks and conditional logic to distinguish between leaf nodes and composite containers, making it fragile and difficult to extend with new node types.

Solution

Define a Component interface that declares operations common to both leaf and composite objects. Leaf nodes implement the operations directly. Composite nodes store child components and implement operations by delegating to each child. Because both conform to the same interface, clients traverse and manipulate the entire tree uniformly.

Participants

Component -- declares the shared interface for leaf and composite objects
Leaf -- represents end objects that have no children
Composite -- stores child Components and implements operations by iterating over children
Client -- manipulates objects through the Component interface

Advantages

Clients treat leaf and composite objects uniformly, reducing conditional logic
Easy to add new kinds of components -- they just implement the Component interface
Recursive structures are naturally modeled and traversed
Simplifies client code by eliminating the need to distinguish between node types

Disadvantages

Making the design too general can make it hard to restrict the types of children a composite accepts
Type safety is weaker -- the shared interface may include operations meaningless for leaves (e.g., addChild)
Can make designs overly abstract if the hierarchy is simple
Ordering or limiting children often requires extra bookkeeping

Real-World Analogy

An organizational chart is a composite structure. A department (composite) contains teams, which contain individual employees (leaves). When the CEO asks for total headcount, the request propagates down the tree: each department sums its teams, each team sums its members, and the results bubble up. The CEO does not care whether a node is a person or a department -- the count operation works uniformly.

Use Cases

File system: files (leaves) and directories (composites) sharing a common FileSystemNode interface
UI component trees: containers that hold buttons, text fields, and other containers
Organization charts: employees and departments with a common getHeadcount() or getCost() method
Menu systems: menu items and sub-menus rendered through the same interface
Arithmetic expression trees: numbers (leaves) and operations (composites) with a common evaluate() method

Code Examples

composite.ts

// Component interface
interface FileSystemNode {
  name: string;
  getSize(): number;
  print(indent?: string): void;
}

// Leaf
class File implements FileSystemNode {
  constructor(
    public readonly name: string,
    private readonly size: number,
  ) {}

  getSize(): number {
    return this.size;
  }

  print(indent = ""): void {
    console.log(`${indent}${this.name} (${this.size} bytes)`);
  }
}

// Composite
class Directory implements FileSystemNode {
  private children: FileSystemNode[] = [];

  constructor(public readonly name: string) {}

  add(child: FileSystemNode): this {
    this.children.push(child);
    return this;
  }

  remove(child: FileSystemNode): void {
    this.children = this.children.filter((c) => c !== child);
  }

  getSize(): number {
    return this.children.reduce((sum, child) => sum + child.getSize(), 0);
  }

  print(indent = ""): void {
    console.log(`${indent}${this.name}/`);
    for (const child of this.children) {
      child.print(indent + "  ");
    }
  }
}

// Build and use the tree uniformly
const root = new Directory("project");
const src = new Directory("src");
src.add(new File("index.ts", 1200));
src.add(new File("utils.ts", 800));

const docs = new Directory("docs");
docs.add(new File("README.md", 500));

root.add(src);
root.add(docs);
root.add(new File("package.json", 300));

root.print();
console.log(`Total size: ${root.getSize()} bytes`);

A file-system tree with a common FileSystemNode interface, where File is a leaf and Directory is a composite that recursively computes total size.

Related Patterns