Angular

TypeScript Configuration

Add the Web Component types to your TypeScript configuration:

{
  "compilerOptions": {
    "types": [
      // Recommended: Adds native DOM types (e.g. `querySelector`, `document`)
      "@staticview/ui/types/dom",

      // Recommended: Exposes component types globally (no imports needed)
      "@staticview/ui/types/global",
    ],
  },
}

This provides TypeScript support for the web components in your Angular application.

Note

Angular templates themselves cannot be type-checked for custom elements. Angular has no equivalent of JSX type augmentation, and CUSTOM_ELEMENTS_SCHEMA (below) tells the compiler to accept unknown elements without checking their bindings. Typed access is available in component class code through element references.

Enabling Custom Elements

Add CUSTOM_ELEMENTS_SCHEMA to every component (or NgModule) whose template uses web components:

import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";

@Component({
  selector: "app-root",
  templateUrl: "./app.html",
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class App {}

Importing Web Components

Web components are registered globally in the browser. Import them once in your application’s entry point, before bootstrapping:

import { bootstrapApplication } from "@angular/platform-browser";
import "@staticview/ui/[component-name]";

import { App } from "./app/app";

bootstrapApplication(App);

Important

Do not import web components in multiple files. Import them only once at application startup, before bootstrapApplication, so the custom elements are defined before Angular renders and assigns properties to them.

Setting Properties

Use Angular’s property binding syntax [propertyName] to set JavaScript properties:

<component-name [opened]="isOpen" [disabled]="isDisabled"></component-name>

Setting Attributes

Use plain attributes for static values, or [attr.attribute-name] binding for dynamic ones:

<component-name disabled="true" [attr.close-button]="showCloseButton"></component-name>

Handling Events

Use Angular’s event binding syntax (eventName) to listen for custom events:

<component-name (opened)="handleExpand($event)"></component-name>

Since the template is not type-checked, $event is untyped — type the handler parameter as CustomEvent yourself:

handleExpand(event: CustomEvent) { ... }

Typed Element References

With @staticview/ui/types/global in your TypeScript configuration, every component’s instance type is available globally and pairs with ElementRef for fully typed access to properties and methods:

<component-name #panel></component-name>

import { Component, CUSTOM_ELEMENTS_SCHEMA, viewChild, type ElementRef } from "@angular/core";

@Component({
  /* ... */
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class Example {
  panel = viewChild<ElementRef<ComponentName>>("panel");

  open() {
    this.panel()?.nativeElement.opened; // fully typed
  }
}

Alternatively, import the component’s class type directly from its module instead of using the global types:

import type { ComponentName } from "@staticview/ui/[component-name]";

The global type from @staticview/ui/types/global is slightly richer — it adds typed attribute helpers and typed addEventListener overloads for the component’s custom events on top of the class type.

With @staticview/ui/types/dom, DOM queries are typed as well:

const element = document.querySelector("component-name"); // ComponentName | null

Using Slots

Use children to render the content of the web component:

<component-name>
  <span slot="title">Title</span>
  <span>Content</span>
</component-name>