skip to content

In Angular Material 22, how do `MatBottomSheet` and the CDK's `Dialog` differ from `MatDialog`, and when would you reach for each?

level: seniorimportance: nice to knowfreq 24%

answer

  1. same engine underneath all three
  2. dismiss, not close
  3. one sheet at a time
  4. unstyled, your own container
  5. different data tokens per service

basics

~20 s

All three open content in a CDK overlay. MatBottomSheet is a phone-first panel at the screen bottom with dismiss() and afterDismissed(), one at a time; the CDK Dialog is the unstyled engine with DialogRef.closed, for dialogs you style yourself.

solid answer

~40 s

`MatDialog` and `MatBottomSheet` are both built on the CDK's `Dialog` from `@angular/cdk/dialog`, so they share the config vocabulary: `data`, `disableClose`, `autoFocus`, `restoreFocus`, `closeOnNavigation`. `MatBottomSheet` anchors a Material panel to the bottom edge, which suits a share sheet on phones; its reference uses `dismiss(result)` and `afterDismissed()`, its data token is `MAT_BOTTOM_SHEET_DATA`, it has no `closePredicate`, and only one sheet is open at a time. The CDK `Dialog` returns a `DialogRef` whose `closed` is an observable property, reads `DIALOG_DATA`, and ships only structural styles, so I reach for it when an in-house design must not look like Material, styling the component myself or supplying a container that extends `CdkDialogContainer`.

code

ts · 28 lines
ts
import {Component, inject} from '@angular/core';
import {MAT_BOTTOM_SHEET_DATA, MatBottomSheet, MatBottomSheetRef} from '@angular/material/bottom-sheet';
import {MatListModule} from '@angular/material/list';

type ShareChoice = 'link' | 'email' | 'csv';

@Component({
  selector: 'app-share-sheet',
  imports: [MatListModule],
  template: `
    <mat-nav-list>
      <a mat-list-item (click)="pick('link')">Copy link to {{ data.name }}</a>
      <a mat-list-item (click)="pick('email')">Invite by email</a>
      <a mat-list-item (click)="pick('csv')">Export CSV</a>
    </mat-nav-list>
  `,
})
export class ShareSheet {
  readonly data = inject<{name: string}>(MAT_BOTTOM_SHEET_DATA);
  private ref = inject<MatBottomSheetRef<ShareSheet, ShareChoice>>(MatBottomSheetRef);
  pick(choice: ShareChoice) { this.ref.dismiss(choice); }
}

export function openShare(sheet: MatBottomSheet, name: string) {
  return sheet.open<ShareSheet, {name: string}, ShareChoice>(ShareSheet, {
    data: {name}, ariaLabel: 'Share project',
  }).afterDismissed();
}

go deeper

for a junior

Recall that MatBottomSheet opens a panel from the bottom and closes with dismiss(), and that the CDK Dialog is an unstyled dialog service.

for a middle

Explain the differences in reference methods, data tokens and default-options tokens, and the one-sheet-at-a-time rule.

for a senior

Choose between the three for a given surface and device, and know what the CDK route costs: styles, container, directives and animation.

for a principal

Decide whether an in-house design system should wrap the CDK Dialog or theme MatDialog, weighing control against the work Material already does.

## One engine, three front ends The CDK's **`Dialog`** service, from `@angular/cdk/dialog`, is the engine: it creates an overlay, attaches your component or template in a container, traps and restores focus, handles Escape and the backdrop, and returns a reference. Angular Material builds two services on it: - **`MatDialog`**: a centred Material 3 dialog with animations and the title, content, actions and close directives; - **`MatBottomSheet`**: a Material panel anchored to the bottom edge of the viewport. Because they share the engine, their configs share most option names, and the focus and dismissal behaviour carries over. ## The differences that show up in code | | `MatDialog` | `MatBottomSheet` | CDK `Dialog` | |---|---|---|---| | Import | `@angular/material/dialog` | `@angular/material/bottom-sheet` | `@angular/cdk/dialog` | | Reference | `MatDialogRef` | `MatBottomSheetRef` | `DialogRef` | | Close from code | `close(result)` | `dismiss(result)` | `close(result)` | | Result | `afterClosed()` method | `afterDismissed()` method | `closed` property | | Data token | `MAT_DIALOG_DATA` | `MAT_BOTTOM_SHEET_DATA` | `DIALOG_DATA` | | App defaults | `MAT_DIALOG_DEFAULT_OPTIONS` | `MAT_BOTTOM_SHEET_DEFAULT_OPTIONS` | `DEFAULT_DIALOG_CONFIG` | | Several open | yes, tracked in `openDialogs` | no, a new one dismisses the current | yes, tracked in `openDialogs` | | `closePredicate` | yes | no | yes | | Look | Material 3 styles and animation | Material 3 styles and animation | structural styles only | Two traps follow from the table: 1. Code moved from a dialog to a bottom sheet that still calls `close()` or `afterClosed()` does not compile: the sheet's methods are `dismiss()` and `afterDismissed()`. 2. The CDK's `closed` is a property, so `dialogRef.closed.subscribe(...)`, not `dialogRef.closed()`. 3. All three default-options tokens **replace** the built-in defaults rather than merging with them, so spread `new MatDialogConfig()`, `new MatBottomSheetConfig()` or `new DialogConfig()` into the provided object first. All three also accept a `TemplateRef` instead of a component. The template context exposes the reference as `dialogRef` for both dialog services and as `bottomSheetRef` for the sheet, next to the data as the implicit `let-data` value. ## When the bottom sheet fits Material's guide positions `MatBottomSheet` primarily for **mobile**, as an alternative to dialogs and menus. In a project tracker, the share action on a phone is the natural fit: "Copy link", "Invite by email", "Export CSV" as a list of actions in a panel that rises from the bottom, within thumb reach. Things to remember: - **One at a time**: opening a second sheet dismisses the first, much like the snack bar. - It is still a modal dialog for assistive technology, with `role="dialog"`, so give it an `ariaLabel` in the config. - Its config has `height`, `minHeight` and `maxHeight` but no width or position options; it always sits at the bottom, spanning up to the full width. - A component inside can inject `MatBottomSheetRef` to dismiss itself with a result. A common pattern is to choose at runtime: the sheet on narrow screens, a menu or dialog on wide ones, using the CDK's breakpoint observer. ## When the CDK `Dialog` fits Reach for the CDK `Dialog` when the dialog **must not look like Material**, typically in a company design system that uses the CDK's behaviour but its own visual language. What changes: - **Styling is yours.** Only structural overlay styles ship. Without a Material theme in the app, include them yourself: `@import '@angular/cdk/overlay-prebuilt.css'` or `@include cdk.overlay()`. - Style the dialog component's `:host`, add global styles through `panelClass`, or provide a **custom container** through the `container` option, typically a component that extends `CdkDialogContainer` to keep focus management. - **No Material directives**: `mat-dialog-close` and `mat-dialog-title` belong to `MatDialog`. Close by injecting `DialogRef` and calling `close(value)`. - **No Material motion**: the enter and exit animation of `MatDialog` comes from Material's container, so with the CDK you add your own if the design needs it. - Positioning is set through the `positionStrategy` option; the strategies themselves are the overlay package's subject. ## How to choose - Material app, a decision or a form: `MatDialog`. - Material app, a list of actions on a phone: `MatBottomSheet`. - Own design system, Material's behaviour without its look: the CDK `Dialog`. The cost of the CDK route is everything Material had done for you: container styling, animation, the content directives and theme integration.

  • Why does a team that uses the CDK Dialog without Angular Material sometimes see the dialog render inline at the bottom of the page?
    The overlay's structural styles are missing. Material's theme includes them, but a CDK-only app must add `@angular/cdk/overlay-prebuilt.css` or `@include cdk.overlay()` itself. Without them the overlay container is not positioned over the page, so the dialog content appears in normal document flow.
  • How do you give a CDK Dialog a custom frame while keeping its focus handling?
    Write a container component that extends `CdkDialogContainer` and pass it through the config's `container` option. The subclass inherits focus trapping, initial focus and restoration, and its own template and styles define the frame around the dialog content, which keeps that chrome out of every individual dialog component.

  • MatBottomSheetRef has close() and afterClosed(), just like MatDialogRef.
  • Several bottom sheets can be stacked like dialogs.
  • The CDK Dialog supports mat-dialog-close and mat-dialog-title.
  • DialogRef.closed() is a method you call to get the result.
  • The CDK Dialog needs no styles of its own outside a Material app.