Composite vs Decorator Pattern in C#: Key Differences Explained

If you've studied the Gang of Four structural patterns, you've probably noticed something suspicious about the composite and decorator. Both implement a shared interface. Both use recursive composition -- an object that contains other objects of the same type. Both let you build object structures that clients interact with uniformly. So why are they separate patterns? The composite vs decorator pattern in C# comparison is one of the easiest to get tangled up in because the structural similarity is real, but the purpose behind each pattern is fundamentally different.

The composite pattern builds tree structures where individual objects and groups of objects are treated the same way. The decorator pattern wraps a single object to layer additional behavior on top. One is about structure. The other is about behavior. In this article, we'll break down each pattern individually, compare their implementations side by side using a shared UI rendering domain, and give you clear criteria for choosing between them. If you want to see how these patterns fit alongside the full catalog of GoF patterns, check out The Big List of Design Patterns for a comprehensive overview.

Quick Refresher: The Composite Pattern

The composite pattern lets you compose objects into tree structures to represent part-whole hierarchies. Individual objects (leaves) and groups of objects (composites) implement the same interface, so client code treats them uniformly. A single button and a panel containing ten buttons are both renderable components -- the client calls Render() on either one without knowing or caring which type it's working with.

The defining characteristic is that a composite node holds a collection of children. It aggregates multiple objects of the same interface type. When you call an operation on the composite, it iterates over its children and delegates the operation to each one. This recursive delegation is what makes tree structures like file systems, UI component trees, and organization hierarchies work naturally.

Here's a minimal example using a UI component hierarchy:

using System;
using System.Collections.Generic;

public interface IUIComponent
{
    void Render(int indent);
}

public sealed class Button : IUIComponent
{
    private readonly string _label;

    public Button(string label)
    {
        _label = label;
    }

    public void Render(int indent)
    {
        Console.WriteLine(
            $"{new string(' ', indent)}<Button>{_label}</Button>");
    }
}

public sealed class Panel : IUIComponent
{
    private readonly string _name;
    private readonly List<IUIComponent> _children = new();

    public Panel(string name)
    {
        _name = name;
    }

    public void Add(IUIComponent component)
    {
        _children.Add(component);
    }

    public void Render(int indent)
    {
        Console.WriteLine(
            $"{new string(' ', indent)}<Panel name="{_name}">");
        foreach (var child in _children)
        {
            child.Render(indent + 2);
        }

        Console.WriteLine(
            $"{new string(' ', indent)}</Panel>");
    }
}

The Panel class is the composite. It holds a List<IUIComponent> and delegates Render to each child. A Button is a leaf -- it has no children and handles the operation directly. Client code can nest panels inside panels to any depth, and a single Render() call cascades through the entire tree. For more on how compositional object structures work in practice, take a look at examples of composition in C#.

Quick Refresher: The Decorator Pattern

The decorator pattern wraps an existing object to add new behavior without modifying the original class. The decorator implements the same interface as the object it wraps, receives that object through its constructor, and delegates calls to it -- but layers additional functionality before, after, or around the delegation.

The defining characteristic of the decorator is that it holds a single wrapped object, not a collection. It doesn't aggregate. It enhances. The decorator always forwards the call to the inner object -- it never decides whether to skip the delegation. Decorators are stackable: you can wrap a decorator in another decorator to compose multiple behaviors together, and removing or reordering layers doesn't affect the others.

Here's a decorator that adds a border around any UI component:

using System;

public sealed class BorderDecorator : IUIComponent
{
    private readonly IUIComponent _inner;
    private readonly string _borderStyle;

    public BorderDecorator(
        IUIComponent inner,
        string borderStyle)
    {
        _inner = inner;
        _borderStyle = borderStyle;
    }

    public void Render(int indent)
    {
        Console.WriteLine(
            $"{new string(' ', indent)}" +
            $"<Border style="{_borderStyle}">");
        _inner.Render(indent + 2);
        Console.WriteLine(
            $"{new string(' ', indent)}</Border>");
    }
}

The BorderDecorator holds a single IUIComponent -- not a list. It wraps that one component, adds border rendering around it, and always delegates to the inner object. The client can wrap a Button in a BorderDecorator to give it a border, or stack a ShadowDecorator on top of that to add a shadow as well. For a deep dive into the decorator pattern's mechanics and real-world usage, see the Decorator Design Pattern in C# Complete Guide.

The Key Difference: Purpose

Here's the single most important distinction in the composite vs decorator pattern in C# comparison:

• Composite structures objects. It builds tree hierarchies where operations cascade through the entire structure.
• Decorator enhances behavior. It wraps a single object to layer additional functionality on top.

The composite pattern is about managing many children. A composite node holds a List<IComponent> and iterates over every child when performing an operation. The operation fans out across the tree. The decorator pattern is about wrapping one object. A decorator holds a single IComponent reference and adds behavior around that one delegation.

Think of it this way: a composite is like a folder on your desktop. It contains files and other folders, and when you copy the folder, everything inside it gets copied too. A decorator is like a gift wrapper -- it wraps a single item, adds a visual layer on top, and doesn't change the item itself. You wouldn't wrap ten items in one sheet of wrapping paper. You wouldn't put a single file inside a folder just to rename it.

The composite aggregates. The decorator augments. Both use the same interface-based composition technique, but for entirely different reasons.

Side-by-Side Code Comparison

The best way to see the composite vs decorator pattern in C# difference is to implement both patterns in the same domain. We'll continue with the UI component example: the composite builds a panel containing buttons and sub-panels, while the decorator wraps an individual component to add visual decoration.

Composite: A Panel of Components

Using the same IUIComponent interface, Button, and Panel from the refresher above, we add a TextBox leaf to broaden the example:

using System;

public sealed class TextBox : IUIComponent
{
    private readonly string _placeholder;

    public TextBox(string placeholder)
    {
        _placeholder = placeholder;
    }

    public void Render(int indent)
    {
        Console.WriteLine(
            $"{new string(' ', indent)}" +
            $"<TextBox placeholder="{_placeholder}" />");
    }
}

The Panel composite manages a collection of children. Calling Render on the panel cascades through every child in the tree. You can build arbitrarily deep structures by nesting panels inside panels.

Decorator: Wrapping a Single Component

using System;

public sealed class ShadowDecorator : IUIComponent
{
    private readonly IUIComponent _inner;
    private readonly int _depth;

    public ShadowDecorator(IUIComponent inner, int depth)
    {
        _inner = inner;
        _depth = depth;
    }

    public void Render(int indent)
    {
        Console.WriteLine(
            $"{new string(' ', indent)}" +
            $"<Shadow depth="{_depth}">");
        _inner.Render(indent + 2);
        Console.WriteLine(
            $"{new string(' ', indent)}</Shadow>");
    }
}

The ShadowDecorator wraps exactly one component and adds shadow rendering around it. It doesn't manage children. It doesn't iterate over a list. It enhances a single object and always forwards the call.

Building Both Structures Together

Here's how these patterns look when assembled in a program entry point:

using System;

public static class Program
{
    public static void Main()
    {
        // Composite: build a tree structure
        var mainPanel = new Panel("MainPanel");
        var submitButton = new Button("Submit");
        var cancelButton = new Button("Cancel");
        var searchBox = new TextBox("Search...");

        var toolbar = new Panel("Toolbar");
        toolbar.Add(submitButton);
        toolbar.Add(cancelButton);

        mainPanel.Add(toolbar);
        mainPanel.Add(searchBox);

        Console.WriteLine("=== Composite Tree ===");
        mainPanel.Render(0);

        Console.WriteLine();

        // Decorator: wrap individual components
        IUIComponent decoratedButton =
            new BorderDecorator(
                new ShadowDecorator(
                    new Button("Fancy Button"),
                    depth: 3),
                borderStyle: "solid");

        Console.WriteLine("=== Decorated Component ===");
        decoratedButton.Render(0);
    }
}

Notice the difference in how the objects are assembled. The composite builds a tree by adding children to parent containers. The decorator wraps one object inside another, creating a chain. The composite fans out. The decorator drills in.

Structural Comparison

Both the composite and decorator patterns implement the same interface, and both hold references to objects of that interface type. That's where the structural similarity ends. The way they hold those references reveals the fundamental difference between the patterns.

Composite holds a collection:

IUIComponent (interface)
  ├── Button (leaf) -- implements Render directly
  ├── TextBox (leaf) -- implements Render directly
  └── Panel (composite) -- holds List<IUIComponent>
        ├── child: IUIComponent
        ├── child: IUIComponent
        └── child: IUIComponent

Decorator holds a single reference:

IUIComponent (interface)
  ├── Button (concrete) -- implements Render directly
  ├── BorderDecorator -- holds one IUIComponent
  │     └── wraps: IUIComponent
  └── ShadowDecorator -- holds one IUIComponent
        └── wraps: IUIComponent

The composite's List<IUIComponent> is the structural fingerprint that distinguishes it from the decorator's single IUIComponent field. When you see a class that implements an interface and holds a collection of that same interface type, you're looking at a composite. When you see a class that implements an interface and wraps a single instance of that same interface type, you're looking at a decorator.

This structural distinction maps directly to the behavioral distinction. The composite iterates over its children -- its operation fans out across the tree. The decorator delegates to its single wrapped object -- its operation flows through a linear chain.

For more on how structural patterns use wrapping and interface-sharing techniques differently, the decorator vs proxy pattern in C# comparison explores another pair of patterns with similar structures but different intents.

When to Choose Composite

The composite pattern is the right choice when your problem domain naturally involves tree structures or part-whole hierarchies. Reach for the composite when these conditions apply:

Representing recursive data structures. File systems, organization hierarchies, menu structures, and document object models all involve containers that hold items and other containers. The composite pattern models these cleanly with a uniform interface.

Cascading operations through a hierarchy. When an operation on a parent should automatically apply to all descendants, composite handles it through recursive delegation. Rendering an entire UI component tree or calculating the total size of a directory tree are natural examples.

Treating individual elements and groups uniformly. Client code calls the same method regardless of whether it's working with a leaf or a subtree, eliminating conditional logic that distinguishes between "single item" and "collection of items."

When to Choose Decorator

The decorator pattern is your tool when you need to extend or modify the behavior of individual objects without altering their class definitions. Reach for the decorator when these conditions apply:

Adding cross-cutting concerns. Logging, timing, validation, retry logic, and caching apply uniformly across many services. The decorator lets you write each concern once and wrap it around any object that implements the target interface.

Composing behavior dynamically. Different configurations need different combinations of behavior. You might add logging and caching in production but only logging in development. Each decorator is independent, and you control the combination through your DI setup.

Respecting the Open/Closed Principle. When modifying the original class is impractical -- maybe it's in a third-party library or a stable, well-tested class -- decorators let you add behavior without touching the source. For guidance on structuring decorator patterns alongside other structural patterns like the facade pattern, consider how each simplifies different aspects of your design.

Can You Combine Them?

The composite vs decorator pattern in C# comparison isn't an either-or decision. These patterns complement each other naturally, and combining them is a common and powerful technique in real-world applications.

The most straightforward combination is decorating individual nodes within a composite tree. You might have a panel (composite) that contains a bordered button (decorated leaf). The panel doesn't know or care that one of its children is wrapped in a decorator. It just calls Render() on each child, and the decorator handles its embellishment transparently.

using System;

public static class CombinedExample
{
    public static void Main()
    {
        var form = new Panel("LoginForm");

        // Plain leaf
        var usernameField = new TextBox("Username");

        // Decorated leaf: button wrapped in decorators
        IUIComponent loginButton =
            new BorderDecorator(
                new ShadowDecorator(
                    new Button("Log In"),
                    depth: 2),
                borderStyle: "rounded");

        // Decorated composite: an entire sub-panel
        // wrapped in a decorator
        var buttonBar = new Panel("ButtonBar");
        buttonBar.Add(new Button("Cancel"));
        buttonBar.Add(new Button("Reset"));

        IUIComponent borderedButtonBar =
            new BorderDecorator(
                buttonBar,
                borderStyle: "dashed");

        // Assemble the tree with mixed nodes
        form.Add(usernameField);
        form.Add(loginButton);
        form.Add(borderedButtonBar);

        form.Render(0);
    }
}

This example shows three combination techniques in one tree. First, a plain leaf (usernameField) sits in the tree with no decoration. Second, a decorated leaf (loginButton) has both a shadow and a border wrapped around it. Third, an entire composite (buttonBar) is wrapped in a BorderDecorator, so the border renders around the entire sub-panel and all its children.

The decorator doesn't care whether it's wrapping a leaf or a composite -- it just wraps whatever IUIComponent it receives. The composite doesn't care whether its children are plain leaves, other composites, or decorated objects -- it just calls Render() on each child. This mutual ignorance is what makes the combination so flexible. It's the same principle of interface conformance that makes the adapter pattern work -- transparent substitution through a shared contract.

Comparison Summary Table

Here's a quick-reference table summarizing the composite vs decorator pattern in C# differences:

Both patterns rely on a shared interface and recursive composition. The composite uses that composition to build branching tree structures. The decorator uses it to build linear chains of behavior.

Frequently Asked Questions

What is the main difference between composite and decorator?

The main difference is purpose. The composite pattern organizes objects into tree structures where operations cascade through the hierarchy. The decorator pattern wraps a single object to add behavior on top. Composite manages many children through a collection. Decorator wraps exactly one object. Even though both implement the same interface and use recursive composition, composite is about structure while decorator is about behavior enhancement.

Can a decorator wrap a composite node?

Yes. Because both patterns implement the same interface, a decorator can wrap a composite node just as easily as it wraps a leaf. When you wrap a Panel in a BorderDecorator, the border renders around the entire panel and all its children. The decorator doesn't know it's wrapping a composite -- it just delegates to whatever IUIComponent it received. This is one of the most practical ways to combine the two patterns in production code.

Why do composite and decorator look so similar in UML?

Both patterns use recursive composition: a class that implements an interface and holds a reference to objects of that same interface type. The difference is in multiplicity. A composite holds a collection (one-to-many), while a decorator holds a single reference (one-to-one). The structural similarity is intentional and is what allows them to work together seamlessly.

How does the composite pattern relate to object composition in C#?

The composite pattern is a specific application of the broader principle of composition in C#. Object composition means building complex objects by combining simpler ones. The composite pattern formalizes this into a recursive tree structure with a uniform interface. Not all composition is the composite pattern, but the composite pattern is always composition.

Can I use both patterns with dependency injection in C#?

Yes. Decorators work naturally with DI containers -- most containers support registering decorators through factory delegates or specialized extension methods like Scrutor. Composites can also be assembled through DI by injecting IEnumerable<IComponent> to populate the children collection. When combining both patterns, build the composite tree first and then wrap the result in decorators using your DI composition root.

How do these patterns differ from the strategy pattern?

The strategy pattern is a behavioral pattern that swaps an algorithm at runtime by injecting different implementations of the same interface. It doesn't wrap or contain other strategies -- it replaces them. The composite and decorator are structural patterns that compose objects together. A strategy selects one behavior. A decorator layers behavior. A composite organizes structure. They solve different problems and can be used together when needed.

Wrapping Up Composite vs Decorator in C#

The composite vs decorator pattern in C# distinction boils down to one question: are you building a structure or enhancing behavior? If your problem involves tree hierarchies where operations cascade through parents to children, the composite pattern models that naturally. If your problem involves layering additional behavior onto individual objects without modifying their classes, the decorator pattern is the right fit.

Both patterns share the same interface-based composition technique, which is exactly what makes them compatible. A composite tree can contain decorated nodes. A decorator can wrap a composite subtree. They compose freely because they follow the same interface contract. The difference is never in the structure of the code -- it's in the intent behind it. Learn to see that intent, and you'll never confuse the two again.