Decorators

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.

Lit supplies a set of decorators that reduce the amount of boilerplate code you need to write when defining a component. For example, the @customElement and @property decorators make a basic element definition more compact:

@customElement('my-element')
export class MyElement extends LitElement {
  @property() greeting = "Welcome";
  @property() name = "Sally";
  @property({type: Boolean}) emphatic = true;
  //...
}

The @customElement decorator defines a custom element, equivalent to calling:

customElements.define('my-element', MyElement);

The @property decorator declares a reactive property.

See Reactive properties for more information about configuring properties.

You can import all the lit decorators via the lit/decorators.js module:

import {customElement, property, eventOptions, query} from 'lit/decorators.js';

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,

import {customElement} from 'lit/decorators/custom-element.js';
import {eventOptions} from 'lit/decorators/event-options.js';

To use decorators, you need to build your code with a compiler such as TypeScript or Babel.

In the future when decorators become a native web platform feature, this may no longer be necessary.

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 false.

"experimentalDecorators": true,
"useDefineForClassFields": false,

Enabling emitDecoratorMetadata is not required and not recommended.

If you're compiling JavaScript with Babel, you can enable decorators by adding the following plugins and settings:

• @babel/plugin-proposal-decorators
• @babel/plugin-proposal-class-properties

Note, the @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:

"assumptions": {
  "setPublicClassFields": true
},
"plugins": [
  ["@babel/plugin-proposal-decorators", {
    "version": "2018-09",
    "decoratorsBeforeExport": true
  }],
  ["@babel/plugin-proposal-class-properties"]
]

When using TypeScript with Babel, it's important to order the TypeScript transform before the decorators transform in your Babel config as follows:

{
  "assumptions": {
    "setPublicClassFields": true
  },
  "plugins": [
    ["@babel/plugin-transform-typescript", {
      "allowDeclareFields": true
    }],
    ["@babel/plugin-proposal-decorators", {
      "version": "2018-09",
      "decoratorsBeforeExport": true
    }],
    ["@babel/plugin-proposal-class-properties"]
  ]
}

The 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,

static properties = { foo: {} };

declare foo: string;

constructor() {
  super();
  this.foo = 'bar';
}

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.

When using decorators, transpiler settings for Babel and TypeScript must be configured correctly as shown in the sections above for TypeScript and Babel.

Edit this page