Migrate from Angular Material

Set up an Angular app

Install the tokens and the components you use, and load the tokens stylesheet once, from angular.json's styles or your global stylesheet:

npm install @lit-material/tokens @lit-material/button @lit-material/text-field

/* src/styles.css */
@import "@lit-material/tokens/css/index.css";

Import each package for its side effect (it registers the elements) and add CUSTOM_ELEMENTS_SCHEMA to every component whose template uses them:

import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import "@lit-material/button";
import "@lit-material/text-field";

@Component({
  selector: "app-profile",
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <lit-material-text-field label="Name" [value]="name" (input)="name = $any($event.target).value"></lit-material-text-field>
    <lit-material-button variant="filled" [disabled]="!name" (click)="save()">Save</lit-material-button>
  `,
})
export class ProfileComponent {
  name = "";
  save() {}
}

Angular Material's Sass theme doesn't carry over. Set the --md-sys-color-* tokens, or make a palette with the theme builder.

Properties, attributes and events

[value] sets a property, which is how arrays and objects go in ([rows]="rows", [options]="options"); [attr.aria-label] sets an attribute; (change) listens to an event, hyphenated names included: (page-change)="onPage($any($event).detail)". Under CUSTOM_ELEMENTS_SCHEMA Angular doesn't type-check these bindings, and $event.target is a plain EventTarget, hence $any(). Each package's dist/web-types.json and VS Code custom data give completion in templates; see React, Vue and Angular.

Forms

lit-material ships no ControlValueAccessor, so formControlName and ngModel don't work on its elements by themselves. What the elements do, checked in Chromium on the elements themselves (not inside an Angular app):

• Text field, textarea, slider: fire input on the element with value already updated, and blur reaches the element; setting value updates the field. That is what Angular's DefaultValueAccessor uses (it writes value and listens for input and blur), so ngDefaultControl selects it: <lit-material-text-field label="Email" formControlName="email" ngDefaultControl>. A slider's value is a number.
• Select: fires only change, so ngDefaultControl would never update the control. Bind [value] and (change), or use an accessor like the one below with value.
• Checkbox, switch, radio: the state is checked and the event is change: [checked]="on" (change)="on = $any($event.target).checked", or an accessor.

An accessor for the checked-state elements is a few lines in your app (it isn't part of lit-material):

import { Directive, ElementRef, HostListener, forwardRef, inject } from "@angular/core";
import { ControlValueAccessor, NG_VALUE_ACCESSOR } from "@angular/forms";

@Directive({
  selector: "lit-material-checkbox[formControlName], lit-material-checkbox[formControl], lit-material-checkbox[ngModel], lit-material-switch[formControlName], lit-material-switch[formControl], lit-material-switch[ngModel]",
  providers: [{ provide: NG_VALUE_ACCESSOR, useExisting: forwardRef(() => CheckedAccessor), multi: true }],
})
export class CheckedAccessor implements ControlValueAccessor {
  private readonly el = inject<ElementRef<HTMLElement & { checked: boolean; disabled: boolean }>>(ElementRef).nativeElement;
  private onChange = (_: boolean) => {};
  private onTouched = () => {};

  @HostListener("change") changed() { this.onChange(this.el.checked); }
  @HostListener("blur") blurred() { this.onTouched(); }

  writeValue(value: boolean) { this.el.checked = !!value; }
  registerOnChange(fn: (value: boolean) => void) { this.onChange = fn; }
  registerOnTouched(fn: () => void) { this.onTouched = fn; }
  setDisabledState(disabled: boolean) { this.el.disabled = disabled; }
}

The fields validate themselves (required, minlength, pattern, min/max) and show the browser's message once touched; Angular's validators run separately. To show an Angular error on a field, bind [error] and [errorText]. Every form field takes part in a native <form>'s FormData.

Component by component

Services become elements

Dialogs. Put lit-material-dialog in the template and drive it with open; close fires however it closes (button, Escape, backdrop). For a yes/no question, confirm() from @lit-material/confirm creates a dialog, awaits the answer and removes it, much like MatDialog.open(…).afterClosed():

<lit-material-dialog [open]="editing" (close)="editing = false">
  <div slot="headline">Edit profile</div>
  <lit-material-text-field label="Name" formControlName="name" ngDefaultControl></lit-material-text-field>
  <div slot="actions"><lit-material-button variant="text" (click)="editing = false">Cancel</lit-material-button></div>
</lit-material-dialog>

import { confirm } from "@lit-material/confirm";

if (await confirm({ headline: "Delete project?", confirmLabel: "Delete", destructive: true })) this.delete();

Snack bars. Keep one lit-material-snackbar in the app shell and a small service that calls its show(message):

@Injectable({ providedIn: "root" })
export class Snackbar {
  private element?: HTMLElement & { show(message?: string): void };
  attach(element: HTMLElement) { this.element = element as Snackbar["element"]; }
  open(message: string) { this.element?.show(message); }
}

// In the app component, whose template has <lit-material-snackbar #snack></lit-material-snackbar>
private readonly snackbar = inject(Snackbar);
@ViewChild("snack") set snack(ref: ElementRef<HTMLElement>) { this.snackbar.attach(ref.nativeElement); }

Menus and tooltips. They're elements next to their trigger instead of directives on it: <lit-material-menu anchor="more"> opened with (click)="$any(menu).show()" on a template reference #menu, and <lit-material-tooltip anchor="save">Save changes</lit-material-tooltip> after id="save" on the button.

Gaps

• No ControlValueAccessors and no Angular package: the patterns above, in your app.
• No codemod: Angular Material templates use directives and services that don't map one to one; use the table.
• No multiple select, range slider, nested menus, selection list, chip listbox element or radio group element.
• No CDK equivalents (overlay, portal, a11y, drag and drop, virtual scroll); the data table virtualizes its own rows, and @lit-material/sortable reorders lists.
• Tables don't own data: no MatTableDataSource, sort or paginator wiring; you sort and slice rows in response to events.
• Not run inside an Angular app in this repository: the forms behaviour above was checked on the elements in Chromium, against how Angular's DefaultValueAccessor works.