Web Components (Part 4): Lit for Angular Developers

Let’s look at a simple Angular component that renders some markup:

@Component({
  selector: "my-component",
  template: `
    <p>Hello world!<p>
  `,
  styles: [`p { color: blue }`],
})
export class MyComponent {}

It consists of a component class (a controller) with a declaratively defined template and associated styles.

In Lit, the controller class implements a render function to render the UI as a function of the component state (similar to frameworks like React), and defines its styles in a static class field:

@customElement("my-component")
export class MyComponent extends LitElement {
  static styles = css`p { color: red }`;

  render() {
    return html`<p>Hello world!</p>`;
  }
}

To render a dynamic value with Angular, you can create a data binding by referencing any public member of the component class in the template:

@Component({
  selector: "my-component",
  template: `
    <p>Hello {{ name }}!<p>
  `,
})
export class MyComponent {
  name = "Jane";
}

With Lit, you can simply reference any value in the scope of the function body using plain JavaScript rules:

@customElement("my-component")
export class MyComponent extends LitElement {
  name = "Jane";
  render() {
    return html`<p>Hello ${this.name}!</p>`;
  }
}

Angular supports inputs that update the UI if their value changes:

@Component({
  selector: "my-component",
  template: `
    <p>Hello {{ name }}!<p>
  `,
})
export class MyComponent {
  @Input()
  name = "unknown";
}

When used in a template, the component’s input value can be assigned using the bracket syntax:

<my-component [name]="'Jane'"></my-component>

As Lit builds on web standards, it uses the concepts already provided by these standards. In DOM context, an element can have properties and attributes. Lit supports so-called reactive properties that work similar to an Angular input:

@customElement("my-component")
export class MyComponent extends LitElement {
  @property()
  name = "unknown";

  render() {
    return html`<p>Hello ${this.name}!</p>`;
  }
}

The usage in markup is as expected:

<my-component name="Jane"></my-component>

There are cases where values are only used internally, and are not part of a component’s public API. With Angular, we can just omit the @Input() decorator and the UI will still be re-rendered, when the variable is updated:

@Component({
  selector: "my-component",
  template: `
    <button (click)="toggle()">Toggle</button>
    <p *ngIf="expanded">Hello world!<p>
  `,
})
export class MyComponent {
  expanded = false;

  toggle() {
    this.expanded = !expanded;
  }
}

With Lit, if you just create a property and update its value, the UI won’t be re-rendered. But you can create an internal property that behaves just like a reactive property. This is called internal state and can be annotated as follows:

@customElement('my-component')
export class MyComponent extends LitElement {
  @state()
  private expanded = false;

  private toggle() {
    this.expanded = !this.expanded;
  }
  
  render() {
    return html`
      <button @click=${() => this.toggle()}>Toggle</button>
      ${this.expanded ? html`<p>Hello world!</p>` : ""}
    `;
  }
}

You might have noticed in the previous example, that we used Angular’s declarative event binding with the parentheses syntax:

<button (click)="toggle()">Toggle</button>

Lit also supports declarative event handlers with a slightly different syntax:

<button @click=${() => this.toggle()}>Toggle</button>

In Angular, a component may define outputs that emit events when something happens:

@Component({
  selector: 'my-counter',
  template: `
    <p>Count: {{ count }}<p>
    <button (click)="handleIncrement()">+</button>
  `,
})
export class MyCounter {
  @Output()
  increment = new EventEmitter<number>();

  count = 0

  handleIncrement() {
    this.count += 1;
    this.increment.emit(this.count);
  }
}

We can then subscribe to these events using the declarative binding syntax:

@Component({
  template: `
    <my-counter (increment)="handleIncrement($event)"></my-counter>
  `,
})
export class MyComponent {
  handleIncrement(count: number) {
    console.log('Incremented:', count);
  }
}

With Lit we can dispatch regular DOM events to notify if something happens, either by using an existing event type or a CustomEvent:

@customElement('my-counter')
export class MyCounter extends LitElement {
  @state()
  count = 0;
  
  private increment() {
    this.count += 1;
    this.dispatchEvent(new CustomEvent('increment', { bubbles: true, composed: true, detail: this.count }))
  }

  render() {
    return html`
      <p>Count: ${this.count}</p>
      <button @click=${this.increment.bind(this)}>+</button>
    `;
  }
}

The usage then is pretty close to Angular’s:

export class MyComponent extends LitElement {
  private handleIncrement(event: CustomEvent<number>) {
    const count = event.detail;
    console.log('handleIncrement', count); 
  }

  render() {
    return html`
      <my-counter @increment=${this.handleIncrement.bind(this)}></my-counter>
    `;
  }
}

Angular’s default encapsulation mode is „emulated“. It annotates the component’s style rules with a component-specific identifier, such that they only apply to the component’s internal elements:

p[_ngcontent-ng-c3264886457] {
  color: red;
}

Apparently this does not prevent global page styles to apply to a component’s internal elements.

Alternatively, you can explicitely switch to an encapsulation mode that enables shadow DOM for the component:

@Component({
  selector: "my-component",
  template: `
    <p>Hello world!<p>
  `,
  styles: [`p { color: blue }`],
  encapsulation: ViewEncapsulation.ShadowDom,
})
export class MyComponent {}

This way, no styles are leaking in or out of the shadow boundary.

Lit uses shadow DOM encapsulation per default for every component. This inherently prevents any leaking of styles in either direction and hides the internal elements in APIs like document.querySelector. You can use the :host or ::slotted selectors to style the component element itself or slotted elements.

Concerning events, all browser-dispatched UI events (like the click events) are composed, meaning they will pass the shadow boundary. This is not the case for custom events, where the Event.composed option has to be enabled explicitly, or they won’t pass the shadow boundary.

Be aware, that the shadow DOM sure has dragons. So if you wish to create a Lit component without encapsulation, you can achieve this as such:

export class MyComponent extends LitElement {
  // ...
  createRenderRoot() { return this; }
}

Angular supports various lifecycle hooks to react to certain events of a component’s lifecycle:

export class MyComponent {
  constructor() {
    // Component instantiated
  }
  ngOnInit() {
    // Inputs set
  }
  ngAfterViewInit() {
    // DOM available
  }
  ngOnDestroy() {
    // Cleanup
  }

  ngOnChanges(changes: SimpleChanges) {
    // Some input changed
  }
}

As Lit components are just custom elements, you can implement the standard lifecycle callbacks:

export class MyComponent extends LitElement {
  constructor() {
    super();
    // Component instantiated
  }
  connectedCallback() {
    // DOM available
  }
  disconnectedCallback() {
    // Cleanup
  }

  static get observedAttributes() {
    return ['x', 'y'];
  }
  attributeChangedCallback(
    name, oldValue, newValue) {
    // Some attribute changed
  }
}

In Angular templates you can work with expressions that are JavaScript-alike, but come with special rules. It also provides some built-in structural directives, that can be used declaratively.

When rendering Lit templates, you can just use JavaScript/TypeScript expressions. In addition to this, Lit comes with some built-in directives that can be used imperatively.

You can add or remove elements based on a condition using the *ngIf directive:

<button *ngIf="show">Click me</button>

The directive also supports an else branch:

<button *ngIf="show; else elseBlock">
  Click me
</button>
<ng-template #elseBlock>
  No access
</ng-template>

To add/remove elements, you can basically use JavaScript if or ternary expressions:

this.show ? html`<button>Click me</button>` : null

Likewise, else branches are easy:

this.show ? html`<button>Click me</button>` : "No access"

Alternatively you can use the built-in when directive:

when(
  this.show,
  () => html`<button>Click me</button>`,
  () => html`No access`,
)

In Angular templates you can use the *ngFor directive to loop over an array:

<ul>
  <li *ngFor="let item of items">
    {{ item }}
  </li>
</ul>

For a more efficient handling of the DOM elements (e.g. reusing them if the order changes instead of re-rendering the whole list), you can use a trackBy function like trackByItems(item) { return item.id }:

<ul>
  <li *ngFor="let item of items; trackBy: trackByItems">
    ({{item.id}}) {{item.name}}
  </li>
</ul>

In Lit templates, you can just use the JavaScript array’s map function:

html`<ul>
  ${items.map((item) => html`<li>${item}</li>`)}
</ul>`

Or, similar to the when directive, you could also use the built-in map directive.

Similar to Angular’s trackBy, you can use Lit’s repeat directive. Although that is initially slower than map, it then reuses and updates the existing DOM nodes, which provides DOM stability and is perfect for large lists or complex items:

html`<ul>
  ${repeat(items, (item) => item.id,
      (item) => html`<li>(${item.id}) ${item.name}</li>`}
</ul>`