JavaScript Reference ยท JSON, Errors and Reflection
Decorators
Overview of JavaScript decorators: the @decorator syntax, what a decorator receives and returns, the manual equivalent you can run today, and support status.
A decorator is a function that wraps or replaces a class or one of its members, applied with an @ prefix. It lets you add behavior such as logging, caching, validation or registration declaratively, instead of calling helper functions after the class is defined.
Decorators are a proposal for the language, and their syntax is not yet usable as plain JavaScript in browsers or Node.js. Check a compatibility table and the TC39 proposal status before using them. TypeScript and Babel can compile the standard form of the proposal today. What a decorator does is ordinary JavaScript, so you can use the same idea right now without the @ syntax.
// Proposed syntax (needs a compiler) class Service { @logged fetchUser(id) { /* ... */ } }
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
@classDecorator class A { @fieldDecorator field = 1; @methodDecorator method() {} @accessorDecorator get value() { return 1; } @autoDecorator accessor name = "x"; // auto-accessor @(factory(options)) other() {} // decorator factory call }
A decorator is a function with this shape:
function decorator(value, context) { // value: the class, method, getter/setter, field (undefined) or accessor // context: { kind, name, static, private, access, addInitializer, metadata } // return a replacement, or nothing to keep the original }
| Part | Description |
|---|---|
value |
The thing being decorated. For fields it is undefined. |
context.kind |
"class", "method", "getter", "setter", "field" or "accessor". |
context.name |
The member name (a string, symbol or private name description). |
context.static, context.private |
Booleans describing the member. |
context.addInitializer(fn) |
Registers code that runs during class definition or instance construction. |
| Return value | A replacement of the same kind (a new function, class, or initializer function for a field), or undefined to keep the original. |
Usage notes
- Status. The standard decorators are a TC39 proposal; the older
experimentalDecoratorsmode in TypeScript and Babel's legacy mode follow a different design that is incompatible with the standard one. Check which one your tooling uses. - Order. Several decorators on one member are applied from the closest to the declaration outward.
- Factories.
@(withRetries(3))calls a function that returns the actual decorator; parentheses are needed for complex expressions. - Plain alternative. A higher-order function (as in the examples), a mixin or a manual reassignment achieves the same result in any current engine.
thismatters. Replacement methods must usefunctionandapply/call, not arrow functions, so the method still receives the rightthis.- Not for functions. Standard decorators apply to classes and class elements, not to standalone functions or object literal methods.
- Debugging. Wrapped methods may change
name,lengthand stack traces unless you preserve them.
Browser support
Native decorator syntax is not available in browsers by default. Use a compiler such as TypeScript or Babel with the standard decorators option, and check a compatibility table for any engine that has started to ship them.