Decorator Pattern: Add Toppings to Your Objects, One Layer at a Time

🥞 A plain dosa and a hungry customer

Meet Arjun. He is fourteen, always hungry, and every evening after tuition he stops at the same dosa stall near the bus stop in Bengaluru. The stall belongs to Ravi Anna, who has been making dosas for twenty years. Ravi Anna makes one thing very, very well: a plain dosa. Crispy, golden, simple. It costs 40 rupees.

Today Arjun has pocket money, so he gets ideas. "Anna, add masala."

Watch what Ravi Anna does. He does not throw the dosa away and cook a brand new dish called "masala dosa" from zero. He takes the same plain dosa sitting on the tawa and spreads a layer of potato masala on it. Plain dosa becomes masala dosa. Price goes up by 20 rupees.

Arjun is feeling rich. "Cheese also, Anna."

Ravi Anna takes the masala dosa and grates a cheese layer on top of it. Now it is a cheese masala dosa. Another 30 rupees.

Behind Arjun in the queue stands his cousin Sneha, a second-year CSE student who came along for the snack. She wants butter, masala, and cheese. No problem for Ravi Anna. Same plain dosa at the centre, three layers stacked on top, three small additions to the bill.

Sneha watches the stall the way only a CSE student can, and suddenly grabs Arjun's arm. "Did you see? He never invents a new dish. He has one base item and a few toppings. Each topping wraps the dosa below it. Each topping adds its own taste and its own price. And every layered dosa is still, in the end, a dosa — you fold it and eat it the same way."

Now she asks the killer question. "What if the menu was written with classes? PlainDosa, MasalaDosa, CheeseDosa, CheeseMasalaDosa, ButterCheeseMasalaDosa..." Ravi Anna would need a new class for every single combination. With 5 toppings, that is 2 × 2 × 2 × 2 × 2 = 32 classes. With 10 toppings, more than 1000 classes. The poor cook would spend his life writing menu cards instead of making dosas.

Ravi Anna's trick — keep one base, wrap it in layers, each layer adds something — is exactly the Decorator pattern. This whole article is that one stall, told slowly.

The journey shows the whole pattern in miniature. The order phase picks the layers. The cook phase stacks them without ever touching the recipe of the base. The pay phase walks down the stack, adding every layer's price.

What is the Decorator pattern?

Decorator is a structural design pattern that lets you attach new behaviour to a single object by wrapping it inside another object called a decorator. The decorator implements the same interface as the object it wraps. Because the wrapper looks exactly like the thing inside it, you can wrap a wrapper again, and again, stacking as many layers as you want.

Each layer does three things:

1. It holds a reference to the object inside it (the wrappee).
2. It forwards calls to that inner object.
3. It adds its own little bit of behaviour before, after, or around that call.

The client at the end holds just one reference. It calls one method. The call ripples down through every layer, and each layer adds its flavour, just like every topping adds taste to the dosa.

The pattern is also called Wrapper, because that is literally what it does — it wraps.

College corner: Decorator is the textbook proof of the design principle "favour composition over inheritance." Inheritance creates an is-a relationship that is fixed when the class is compiled and applies to every instance of the class forever. Composition creates a has-a relationship that is assembled object by object, while the program runs. The decorator cleverly uses both: it inherits the interface (so it can stand anywhere the component stands — this is the Liskov Substitution Principle doing real work) and it composes the behaviour (so each object can carry a different stack). The result also satisfies the Open/Closed Principle: the system is open to new toppings (just add a class) but closed to modification (nobody edits PlainDosa ever again).

The problem it solves

Let us see what happens without the pattern. Suppose Sneha writes a notification system for her college app. Version one sends messages by email only:

class EmailNotifier {
  send(message: string): void {
    console.log(`Email sent: ${message}`);
  }
}

Soon, parents ask for SMS. Teachers ask for WhatsApp. The principal wants push notifications. So she starts making subclasses:

// The wrong road: one class per combination
class EmailAndSmsNotifier { /* ... */ }
class EmailAndWhatsAppNotifier { /* ... */ }
class EmailAndSmsAndWhatsAppNotifier { /* ... */ }
class SmsAndPushNotifier { /* ... */ }
// ... and it never ends

With n channels, there are 2ⁿ possible combinations. Four channels means up to 16 classes. Five means 32. And there is a second, sneakier problem: inheritance is decided at compile time. Once an object is born as an EmailAndSmsNotifier, it can never become "email only" or "email plus push" while the program runs. The choice is frozen forever — like a dosa that comes out of the kitchen welded to its toppings.

The root cause: inheritance applies to the whole class, not to one object. You cannot tell this particular notifier, "from now on, also send SMS." You need a way to compose behaviours per object, at runtime.

On the left, every new combination needs a new class. On the right, you build any combination by simply choosing which wrappers to stack. Four small classes can give you all sixteen combinations.

How bad does the explosion get as toppings grow? Here is the brutal arithmetic, drawn:

The first line is the subclassing road: 2ⁿ classes, rocketing to 1024 with just ten toppings. The second line is the decorator road: one base plus one small class per topping, crawling along at n + 1. This single chart is the strongest argument for the pattern. When someone asks "why not just subclass?", show them the curve.

⚙️ How it works, step by step

The pattern has four small parts. Follow these steps and you can build it for any problem:

1. Define a Component interface. This is the common shape that both the real object and every wrapper will share. For our dosa stall: getDescription() and getCost().
2. Write the ConcreteComponent. This is the base object that does the real work — the plain dosa. Decorators will add to its behaviour.
3. Write a base Decorator class. It implements the Component interface and stores a reference to another Component (the wrappee). By default, it just forwards every call inward. It is a transparent pass-through.
4. Write ConcreteDecorators. Each one extends the base decorator and overrides a method to add its own behaviour around the forwarded call. Masala adds its name and 20 rupees. Cheese adds its name and 30 rupees.
5. Let the client compose. The client makes a plain dosa, then wraps it in whichever decorators it wants, in whichever order. The final object is still typed as a plain Component.

The magic line is this: a decorator is a Component (so it can stand wherever a component stands) and has a Component (so it can wrap one). That is why decorators stack.

Here is the whole cast of the pattern, mapped onto Ravi Anna's stall:

Read the diagram from top to bottom. PlainDosa and ToppingDecorator both promise to behave like a Dosa. But the decorator also holds a Dosa inside it. So a CheeseTopping can hold a MasalaTopping, which holds a PlainDosa. Three layers, one interface.

It also helps to see the life of one order as states. An order starts as a plain base, gets wrapped any number of times, and is finally served when the bill is totalled:

The loop on Wrapped is the heart of the pattern — you can stay in that state as long as you like, adding layer after layer, because every wrap produces another valid Dosa.

Real-life code example

Let us code the full dosa stall in TypeScript. Watch how the wrappers stack.

// Step 1: The Component interface.
// Every dosa — plain or loaded with toppings — must answer
// these two questions: what are you, and what do you cost?
interface Dosa {
  getDescription(): string;
  getCost(): number;
}
 
// Step 2: The ConcreteComponent — the base item.
class PlainDosa implements Dosa {
  getDescription(): string {
    return "Plain Dosa";
  }
  getCost(): number {
    return 40; // rupees
  }
}
 
// Step 3: The base Decorator.
// It IS a Dosa (implements the interface)
// and it HAS a Dosa (holds the wrappee).
abstract class ToppingDecorator implements Dosa {
  constructor(protected wrappee: Dosa) {}
 
  // By default, just pass the call inward.
  getDescription(): string {
    return this.wrappee.getDescription();
  }
  getCost(): number {
    return this.wrappee.getCost();
  }
}
 
// Step 4: Concrete decorators. Each adds one topping.
class MasalaTopping extends ToppingDecorator {
  getDescription(): string {
    return this.wrappee.getDescription() + " + Masala";
  }
  getCost(): number {
    return this.wrappee.getCost() + 20;
  }
}
 
class CheeseTopping extends ToppingDecorator {
  getDescription(): string {
    return this.wrappee.getDescription() + " + Cheese";
  }
  getCost(): number {
    return this.wrappee.getCost() + 30;
  }
}
 
class ButterTopping extends ToppingDecorator {
  getDescription(): string {
    return this.wrappee.getDescription() + " + Butter";
  }
  getCost(): number {
    return this.wrappee.getCost() + 15;
  }
}
 
// Step 5: The client composes the order — STACKING wrappers.
// Order 1: just a plain dosa.
let order1: Dosa = new PlainDosa();
console.log(`${order1.getDescription()} = Rs.${order1.getCost()}`);
 
// Order 2: masala dosa. Wrap once.
let order2: Dosa = new MasalaTopping(new PlainDosa());
console.log(`${order2.getDescription()} = Rs.${order2.getCost()}`);
 
// Order 3: Sneha's butter cheese masala dosa. Wrap three times!
// Read it from inside out: PlainDosa -> Masala -> Cheese -> Butter.
let order3: Dosa = new ButterTopping(
  new CheeseTopping(
    new MasalaTopping(
      new PlainDosa()
    )
  )
);
console.log(`${order3.getDescription()} = Rs.${order3.getCost()}`);
 
// You can even add a topping AFTER the order is made.
// Arjun leans over: "One more cheese, please!"
order3 = new CheeseTopping(order3);
console.log(`${order3.getDescription()} = Rs.${order3.getCost()}`);

Output:

Plain Dosa = Rs.40
Plain Dosa + Masala = Rs.60
Plain Dosa + Masala + Cheese + Butter = Rs.105
Plain Dosa + Masala + Cheese + Butter + Cheese = Rs.135

Look at the last two lines carefully. We added a second cheese layer to an already finished order, at runtime, with one line of code. No new class. No editing of old classes. Each getCost() call travels down through every layer — butter asks cheese, cheese asks masala, masala asks the plain dosa — and the answer travels back up, growing at every step. That ripple through the layers is the heartbeat of the Decorator pattern.

Here is that ripple, frozen as a sequence diagram. One innocent call from Sneha, four hops down, four answers back up:

Also notice: every order variable is typed as plain Dosa. The client never knows, and never needs to know, how many layers are inside.

And where does Sneha's 105 rupees actually go? Mostly to the base, with each layer taking its small cut:

This pie is a nice mental model for any decorated object: the base contributes the core behaviour, and every wrapper contributes one well-defined slice. If a slice is wrong, you know exactly which class to open.

The same idea in C#

The shape is identical in C#. Here is a compact version with a different flavour — adding logging and emoji to a simple message sender:

// Component
public interface INotifier
{
    void Send(string message);
}
 
// ConcreteComponent — the base behaviour
public class EmailNotifier : INotifier
{
    public void Send(string message)
        => Console.WriteLine($"Email: {message}");
}
 
// Base decorator: is-a INotifier, has-a INotifier
public abstract class NotifierDecorator : INotifier
{
    protected readonly INotifier Wrappee;
    protected NotifierDecorator(INotifier wrappee) => Wrappee = wrappee;
    public virtual void Send(string message) => Wrappee.Send(message);
}
 
// Concrete decorators
public class SmsDecorator : NotifierDecorator
{
    public SmsDecorator(INotifier w) : base(w) { }
    public override void Send(string message)
    {
        base.Send(message);                    // pass inward first
        Console.WriteLine($"SMS: {message}");  // then add behaviour
    }
}
 
public class WhatsAppDecorator : NotifierDecorator
{
    public WhatsAppDecorator(INotifier w) : base(w) { }
    public override void Send(string message)
    {
        base.Send(message);
        Console.WriteLine($"WhatsApp: {message}");
    }
}
 
// Client: stack the layers
INotifier notifier = new WhatsAppDecorator(
                         new SmsDecorator(
                             new EmailNotifier()));
 
notifier.Send("PTM on Friday at 10 AM");
// Output:
// Email: PTM on Friday at 10 AM
// SMS: PTM on Friday at 10 AM
// WhatsApp: PTM on Friday at 10 AM

One call to Send, three channels fire. To change channels, you change which wrappers you stack — not a single class is edited.

A Python flavour, and the question of order

Python makes decorators feel almost weightless, because functions are objects too. Here is the dosa stall again, plus a demonstration of the most important practical rule — order matters:

class PlainDosa:
    def description(self): return "Plain Dosa"
    def cost(self): return 40
 
class Topping:
    """Base decorator: holds the wrappee, forwards by default."""
    def __init__(self, wrappee): self.wrappee = wrappee
    def description(self): return self.wrappee.description()
    def cost(self): return self.wrappee.cost()
 
class Masala(Topping):
    def description(self): return self.wrappee.description() + " + Masala"
    def cost(self): return self.wrappee.cost() + 20
 
class SchezwanSauce(Topping):
    """A spicy wrapper that DOUBLES the price of whatever it covers."""
    def description(self): return self.wrappee.description() + " + Schezwan"
    def cost(self): return self.wrappee.cost() * 2
 
# Order A: masala first, then schezwan doubles (40 + 20) = 120
order_a = SchezwanSauce(Masala(PlainDosa()))
 
# Order B: schezwan doubles the base (40 * 2), then masala adds 20 = 100
order_b = Masala(SchezwanSauce(PlainDosa()))
 
print(order_a.description(), "= Rs.", order_a.cost())   # Rs. 120
print(order_b.description(), "= Rs.", order_b.cost())   # Rs. 100

Same two toppings, same base, different bills — only because the stacking order changed. Twenty rupees of difference from one swapped line.

College corner: this ordering effect is not a toy detail; it is the number one production bug with decorators. Compress-then-encrypt shrinks your data nicely, because compression finds patterns in plain text. Encrypt-then-compress saves almost nothing, because good ciphertext looks like random noise with no patterns left to squeeze. Similarly, in a middleware pipeline, putting the authentication wrapper outside the logging wrapper means failed logins never get logged. The general rule: a decorator can only see and transform what the layers inside it have already produced. Treat the stack order as part of your design, write it down, and test at least one property that breaks if someone reorders it.

Where you see it in real software

The Decorator pattern is not just a textbook idea. It quietly runs inside tools you use every day.

• Java I/O streams. This is the most famous example. new BufferedReader(new InputStreamReader(new FileInputStream("f.txt"))) is three decorator layers. FileInputStream reads raw bytes, InputStreamReader adds character decoding, BufferedReader adds buffering and the handy readLine() method. Each wrapper takes a stream and gives back a richer stream.
• .NET stream wrappers. Exactly the same idea: wrap a FileStream in a GZipStream for compression, then wrap that in a CryptoStream for encryption. Each wrapper is still a Stream, so you can keep stacking.
• Middleware pipelines. Web frameworks like Express (Node.js) and ASP.NET Core pass each request through a chain of middleware — logging, authentication, compression. Each piece wraps the next handler and adds behaviour around it. It is the decorator idea applied to request handling.
• TypeScript/Java annotations and decorators. TypeScript's @decorator syntax and libraries like NestJS use the same spirit: wrap a class or method with extra behaviour (caching, validation, logging) without editing it.
• UI toolkits. Adding a scrollbar or a border around a window component is classically done with decorators — the wrapped widget is still a widget.
• Open-source reference. The java-design-patterns repository by iluwatar has a clean, runnable decorator example (a troll that becomes a "club-wielding troll" by wrapping) with thousands of stars — great for extra reading.

🧭 When to use it and when not to

The same decision, drawn as a map. Find where your problem sits:

The top-right quadrant — many combinations, chosen while the program runs — is decorator country. The bottom-left — one combination, known forever — needs nothing fancier than a subclass or even a plain function.

Common mistakes students make

Compare with cousins

Decorator has two look-alike cousins: Proxy and Adapter. All three wrap an object. The difference is why they wrap.

Also worth one line each:

• Composite holds many children and treats them uniformly; Decorator holds exactly one child and adds behaviour. They often work together in UI trees.
• Strategy changes the insides of an object by plugging in a different algorithm; Decorator changes the skin by wrapping around it.
• Chain of Responsibility also passes calls along linked objects, but a handler may stop the chain; in a decorator stack, every layer is expected to forward.

Everything in this article, hung on one tree:

Quick revision box

+--------------------------------------------------------------+
|                  DECORATOR — QUICK REVISION                   |
+--------------------------------------------------------------+
| Idea      : Wrap an object to add behaviour. Same interface. |
| Nickname  : Wrapper                                          |
| Analogy   : Plain dosa + masala + cheese + butter layers     |
| Key trick : Decorator IS-A Component and HAS-A Component     |
|             -> so wrappers can stack on wrappers             |
| Parts     : Component, ConcreteComponent,                    |
|             BaseDecorator, ConcreteDecorators                |
| Wins      : No 2^n subclass explosion; add/remove at runtime |
| Watch out : Layer ORDER matters; always forward the call;    |
|             instanceof checks break on wrapped objects       |
| Cousins   : Proxy (controls access), Adapter (new interface) |
| Real life : Java BufferedReader, .NET GZipStream/CryptoStream|
|             Express / ASP.NET middleware pipelines           |
+--------------------------------------------------------------+

Practice exercise 📝

Try these on your own. Use the dosa example as your template.

1. Chai stall. Build a Beverage interface with getCost() and getLabel(). Create PlainChai (Rs. 10) as the base, then decorators Ginger (+5), Elaichi (+7), and ExtraStrong (+5). Make a "double ginger elaichi chai" by stacking Ginger twice. Print the label and total.
2. Text pipeline. Create a TextSource interface with read(): string. Base class returns a fixed sentence. Write three decorators: UpperCaseDecorator, TrimDecorator, and StarBorderDecorator (adds *** before and after). Stack them in two different orders and print both results. Explain in one sentence why the outputs differ.
3. Challenge — unwrap. Our pattern makes removing a middle layer hard. Write a small function that rebuilds a decorator stack without one given topping (hint: keep the toppings in an array, then fold/reduce the array into a stack). This teaches you why many real systems configure decorators from a list.
4. College challenge — measure the explosion. Write a tiny script that prints, for n = 1 to 12, the number of classes needed by the subclassing road (2ⁿ) versus the decorator road (n + 1). Then write two sentences on which SOLID principles the decorator road satisfies and why.