Perfect! Let’s map out Angular Material & CDK services/components and classify them for SSR safety. This will clarify why your current mocks are necessary.
SSR Safety Map for Angular Material / CDK
| Service / Component | Server-Safe? | Notes / SSR Issue | Recommendation |
|---|---|---|---|
| MatDialog | ❌ Not safe | Calls Overlay.create(), which touches document. |
Mock with MockMatDialog |
| MatSnackBar | ❌ Not safe | Similar to Dialog, uses Overlay internally. | Mock with MockMatSnackBar |
| Overlay (CDK) | ❌ Not safe | Core DOM service for popups/portals. Always crashes on SSR. | Must mock (MockOverlay) |
| MatBottomSheet | ❌ Not safe | Uses Overlay under the hood. | Mock (MockMatBottomSheet) |
| MatTooltip | ⚠️ Usually safe | Mostly attaches to host element lazily, but Overlay internally may be used. |
Optional mock for default options, safe to just provide MAT_TOOLTIP_DEFAULT_OPTIONS |
| MatMenu | ⚠️ Usually safe | Uses Overlay internally. Will crash if opened on server. | Guard .open() calls or mock Overlay |
| MatSelect | ⚠️ Usually safe | Overlay for dropdown panel, crash if server tries to render panel. | Mock Overlay or lazy browser-only usage |
| MatAutocomplete | ⚠️ Usually safe | Overlay for dropdown panel. | Same as MatSelect |
| MatTable | ✅ Safe | Purely DOM table rendering. | No mock needed |
| MatPaginator / MatSort | ✅ Safe | Only logic, no Overlay/DOM issues | No mock needed |
| MatFormField / MatInput | ✅ Safe | Basic input rendering | No mock needed |
| MatCheckbox / MatRadio / MatSlideToggle | ✅ Safe | No Overlay, purely DOM | No mock needed |
| MatStepper | ✅ Safe | Pure DOM | No mock needed |
| CDK DragDrop | ⚠️ Conditional | Needs document for coordinates if used |
Guard with isPlatformBrowser |
Summary
-
Must Mock: Dialog, SnackBar, Overlay, BottomSheet
-
Optional / Conditional: Tooltip, Menu, Select, Autocomplete, DragDrop (only if used on server)
-
Safe: Form controls, tables, steppers, checkboxes, radios, inputs
Why Angular doesn’t provide this out-of-the-box
Angular Material assumes browser usage. Server rendering is secondary, so Angular provides no default SSR-safe mocks for Overlay or related services. You must provide them yourself—or guard usage.
If you want, I can enhance your SSR mocks even further so they cover tooltips, menus, selects, and autocomplete safely, without breaking SSR.
Do you want me to do that?
