Decorators are special functions that can modify the behavior of classes, class methods, and class fields. Lit uses decorators to provide declarative APIs for things like registering elements, reactive properties, and queries.
Decorators are a stage 3 proposal for addition to the ECMAScript standard. Currently no browsers implement decorators, but compilers like Babel and TypeScript provide support for an earlier version of the decorators proposal. Lit decorators work with Babel and TypeScript, and will be updated to work with the final specification when it's implemented in browsers.
See the Enabling decorators section for more information.
What does stage 3 mean?
Stage 3 means that the specification text is complete, and ready for browsers to implement. Once the specification has been implemented in multiple browsers, it can move to the final stage, stage 4, and be added to the ECMAScript standard. A stage 3 proposal can still change, but only if critical issues are discovered during implementation.
Lit supplies a set of decorators that reduce the amount of boilerplate code you need to write when defining a component. For example, the
@property decorators make a basic element definition more compact:
@customElement decorator defines a custom element, equivalent to calling:
@property decorator declares a reactive property.
See Reactive properties for more information about configuring properties.
Built-in decoratorsPermalink to “Built-in decorators”
|Defines a custom element||Above|
|Adds event listener options.||Events|
|Defines a public property.||Properties|
|Defines a private state property||Properties|
|Defines a property that returns an element in the component template.||Shadow DOM|
|Defines a property that returns a list of elements in the component template.||Shadow DOM|
|Defines a property that returns a promise that resolves to an element in the component template.||Shadow DOM|
|Defines a property that returns the child elements assigned to a specific slot.||Shadow DOM|
|Defines a property that returns the child nodes assigned to a specific slot.||Shadow DOM|
Importing decoratorsPermalink to “Importing decorators”
You can import all the lit decorators via the
To reduce the amount of code needed to run the component, decorators can be imported individually into component code. All decorators are available at
lit/decorators/<decorator-name>.js. For example,
Enabling decoratorsPermalink to “Enabling decorators”
In the future when decorators become a native web platform feature, this may no longer be necessary.
Using decorators with TypeScriptPermalink to “Using decorators with TypeScript”
To use decorators with TypeScript, enable the
experimentalDecorators compiler option.
You should also ensure that the
useDefineForClassFields setting is
false. Note, this should only be required when the
target is set to
esnext or greater, but it's recommended to explicitly ensure this setting is
emitDecoratorMetadata is not required and not recommended.
Using decorators with BabelPermalink to “Using decorators with Babel ”
@babel/plugin-proposal-class-properties may not be required with the latest versions of Babel.
To set up the plugins, add code like this to your Babel configuration:
Babel decorator support has been tested with
version: '2018-09'. This is currently the default, but we recommend setting the version explicitly in case the default changes. Other versions ('2021-12' or 'legacy') are not supported, but this may change as Babel evolves. See the Babel documentation if you want to experiment.
Using decorators with TypeScript and BabelPermalink to “Using decorators with TypeScript and Babel”
When using TypeScript with Babel, it's important to order the TypeScript transform before the decorators transform in your Babel config as follows:
allowDeclareFields setting is generally not needed, but it can be useful if you want to define a reactive property without using a decorator. For example,
Avoiding issues with class fields and decoratorsPermalink to “Avoiding issues with class fields and decorators”
Class fields have a problematic interaction with declaring reactive properties. See Avoiding issues with class fields when declaring properties for more information.
The current decorators stage 3 proposal does not directly address this issue, but it should be solved as the proposal evolves and matures.