Migrating from Angular Material

Angular Material and Ndop can run in the same app, so you can move one screen at a time. Both build their overlays, focus handling and keyboard support on the Angular CDK, so the two behave alike while they share a page.

This guide was checked against @angular/material 22.2.1 and @angular/cdk 22.2.1, read from their published packages.

What changes

Material's components are installed from npm and styled by its Sass theme. Ndop's styled items are source files in your app: directives that put Tailwind classes on elements you write.

<!-- Angular Material -->
<button matButton="filled">Save</button>

<!-- Ndop -->
<button ndButton>Save</button>

• Directives, not elements. <mat-checkbox> renders its own control and label. ndCheckbox goes on your button, and its label is a separate label element.
• Templates, not services. A Material dialog is a component passed to MatDialog.open(). An Ndop dialog's content is an ng-template in the page, opened by its trigger or by binding [(open)].
• Models for state. Open, value and checked state are two-way bindable models, such as [(value)] on Tabs, which takes a string, not an index.
• Styles are yours. There are no *-overrides mixins: edit the classes in your copy of the item, or pass class, which is merged last.

Components

Ndop also has components Material doesn't: Command, Popover, Hover Card, Navigation Menu, Resizable and Chart, among others.

A dialog, before and after

With Material, the dialog is a component that a service opens:

<h2 mat-dialog-title>Delete project?</h2>
<mat-dialog-content>Its tasks are deleted for everyone.</mat-dialog-content>
<mat-dialog-actions align="end">
  <button matButton mat-dialog-close>Cancel</button>
  <button matButton="filled" [mat-dialog-close]="true">Delete</button>
</mat-dialog-actions>

With Ndop, a confirmation is an Alert Dialog in the page that asks:

import { Component, output } from '@angular/core';
import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger } from '@/ui/alert-dialog/alert-dialog';
import { Button } from '@/ui/button/button';

@Component({
  selector: 'app-delete-project',
  imports: [AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, Button],
  template: `
    <ng-container ndAlertDialog>
      <button ndButton variant="destructive" ndAlertDialogTrigger>Delete project</button>
      <ng-template ndAlertDialogPortal>
        <div ndAlertDialogOverlay></div>
        <div ndAlertDialogContent>
          <div ndAlertDialogHeader>
            <h2 ndAlertDialogTitle>Delete project?</h2>
            <p ndAlertDialogDescription>Its tasks are deleted for everyone.</p>
          </div>
          <div ndAlertDialogFooter>
            <button ndAlertDialogCancel>Cancel</button>
            <button ndAlertDialogAction variant="destructive" (click)="deleted.emit()">Delete</button>
          </div>
        </div>
      </ng-template>
    </ng-container>
  `,
})
export class DeleteProject {
  readonly deleted = output();
}

Both buttons close the dialog, and focus returns to the trigger. Where Material's caller reads the result from afterClosed(), the page listens to (deleted).

Theming

Material builds its theme in Sass, with mat.theme(), and exposes it as --mat-sys-* CSS variables. Ndop's theme is plain CSS variables with shadcn/ui's names, written into your stylesheet by ndop init; see Theming.

To carry your palette over, set each Ndop token to the Material color in the same role:

The theme studio shows the contrast of each pair as you edit, and exports the result as CSS or as a theme URL for ndop add.

The CDK they share

Ndop's primitives use the same CDK as Material: overlays and positioning, focus traps and key managers from a11y, bidi for text direction, and CDK menu, listbox and accordion. In one app:

• Both libraries' overlays open in the CDK's one overlay container, and both read dir through Directionality, so a right-to-left page is right-to-left everywhere.
• Material 22.2.1 requires @angular/cdk at exactly its own version. ndop add installs the CDK only when package.json doesn't list it, so it keeps the version Material needs.
• CDK features you use directly, such as drag and drop, virtual scrolling and BreakpointObserver, don't depend on Material and keep working.
• When you remove @angular/material, keep @angular/cdk: @ndop/primitives needs it.

Migrating step by step

1. Give Tailwind a CSS stylesheet

   ndop init writes Tailwind and the theme into your app's first global stylesheet, which must be a .css file. If yours is styles.scss, list a CSS file before it in the build's styles in angular.json, and keep Material's Sass where it is. init creates the file:

   angular.json

   "styles": ["src/tailwind.css", "src/styles.scss"]

2. Set up Ndop

   Commit your work, then preview the changes and apply them:

   npmpnpmyarnbun

   npx @ndop/cli init --dry-run

   npmpnpmyarnbun

   npx @ndop/cli init

3. Follow one color scheme

   Material's colors follow color-scheme, and Ndop's follow the .dark class and data-ndop-theme="system" that provideNdop() sets on the root element. Replace the color-scheme that Material's ng add set on body with rules that follow Ndop's:

   src/tailwind.css

   html {
     color-scheme: light;
   }
   html.dark {
     color-scheme: dark;
   }
   html[data-ndop-theme='system'] {
     color-scheme: light dark;
   }

4. Move a screen at a time

   Add the components a screen needs, and replace its Material components with the map above:

   npmpnpmyarnbun

   npx @ndop/cli add button dialog form-field input

   Material's global styles aren't in a CSS layer, so they win over Tailwind's, which are. While Material is in the app, the body rule its setup wrote sets the page's background, text color and font. If your Sass includes mat.typography-hierarchy(), its .mat-typography class also styles the headings below it, Ndop's included.

5. Remove Material

   Once no template uses Material, uninstall @angular/material, and delete mat.theme(), the body rule and any typography hierarchy from your Sass. Ndop's base styles then set the page's background, text color and font from your theme.

Next steps

• Theming and Dark mode cover the tokens in detail.
• CLI explains ndop update, which merges later versions into the components you've edited.