From 9c2666cb0b73408e5288f6dee71778ad9ada75d2 Mon Sep 17 00:00:00 2001
From: yogeshwaran-c <ycyogesh183@gmail.com>
Date: Mon, 23 Feb 2026 23:58:17 +0530
Subject: [PATCH] docs(material/dialog): clarify that default options replace
 rather than merge

Add a note to the dialog documentation explaining that providing
MAT_DIALOG_DEFAULT_OPTIONS (or DEFAULT_DIALOG_CONFIG for CDK) replaces
the entire built-in config rather than merging with it. Include the
workaround of spreading the defaults for partial overrides.

Also update the code examples to use bootstrapApplication and
"app config" prose for consistency.

Closes #20631
---
 src/cdk/dialog/dialog.md      | 12 ++++++++++++
 src/material/dialog/dialog.md | 12 ++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/src/cdk/dialog/dialog.md b/src/cdk/dialog/dialog.md
index cfdd2bedbf6f..a324589660ff 100644
--- a/src/cdk/dialog/dialog.md
+++ b/src/cdk/dialog/dialog.md
@@ -129,6 +129,18 @@ bootstrapApplication(MyApp, {
 });
 ```
 
+> **Note:** The value provided for `DEFAULT_DIALOG_CONFIG` **replaces** the built-in defaults
+> entirely rather than merging with them. For example, providing `{disableClose: true}` means that
+> all other defaults (such as `hasBackdrop`) will be `undefined`. If you only want to override
+> specific properties, spread the defaults first:
+>
+> ```ts
+> {provide: DEFAULT_DIALOG_CONFIG, useValue: {...new DialogConfig(), disableClose: true}}
+> ```
+>
+> When you call `dialog.open()` with a config, that config is merged on top of these defaults, so
+> per-dialog options always take precedence.
+
 ### Sharing data with the Dialog component.
 You can use the `data` option to pass information to the dialog component.
 
diff --git a/src/material/dialog/dialog.md b/src/material/dialog/dialog.md
index 43a4cde25a5f..1424d81c9270 100644
--- a/src/material/dialog/dialog.md
+++ b/src/material/dialog/dialog.md
@@ -53,6 +53,18 @@ bootstrapApplication(MyApp, {
 });
 ```
 
+> **Note:** The value provided for `MAT_DIALOG_DEFAULT_OPTIONS` **replaces** the built-in defaults
+> entirely rather than merging with them. For example, providing `{disableClose: true}` means that
+> all other defaults (such as `hasBackdrop`) will be `undefined`. If you only want to override
+> specific properties, spread the defaults first:
+>
+> ```ts
+> {provide: MAT_DIALOG_DEFAULT_OPTIONS, useValue: {...new MatDialogConfig(), disableClose: true}}
+> ```
+>
+> When you call `dialog.open()` with a config, that config is merged on top of these defaults, so
+> per-dialog options always take precedence.
+
 ### Sharing data with the Dialog component.
 If you want to share data with your dialog, you can use the `data`
 option to pass information to the dialog component.