From bbdeb50405d2bda0b83e6e2c6ccd2953834d1c4f Mon Sep 17 00:00:00 2001
From: Michaela Laurencin <35157522+mlaurencin@users.noreply.github.com>
Date: Tue, 28 Apr 2026 12:03:49 -0400
Subject: [PATCH] docs: add further disposition description (#50246)

* docs: add further disposition description

* add option descriptions

* fix linter
---
 docs/api/web-contents.md | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
index a2d4808e6f..04cb555298 100644
--- a/docs/api/web-contents.md
+++ b/docs/api/web-contents.md
@@ -226,7 +226,16 @@ Returns:
     Only defined when the window is being created by a form that set
     `target=_blank`.
   * `disposition` string - Can be `default`, `foreground-tab`,
-    `background-tab`, `new-window` or `other`.
+    `background-tab`, `new-window` or `other`. Corresponds to the manner
+    an associated link was clicked. See Chromium's
+    [WindowOpenDisposition](https://source.chromium.org/chromium/chromium/src/+/main:ui/base/window_open_disposition.h).
+    * `default` - Indicates Chromium deems in-window navigation valid
+      for a window open call.
+    * `foreground-tab` - Corresponds to a left click or shift + middle click.
+    * `background-tab` - Corresponds to a middle click or ctrl/cmd + click.
+    * `new-window` - Corresponds to a shift + left click.
+    * `other` - A catch-all for the remaining Chromium dispositions not
+      handled by Electron.
 
 Emitted _after_ successful creation of a window via `window.open` in the renderer.
 Not emitted if the creation of the window is canceled from
@@ -1449,8 +1458,17 @@ Ignore application menu shortcuts while this web contents is focused.
     * `url` string - The _resolved_ version of the URL passed to `window.open()`. e.g. opening a window with `window.open('foo')` will yield something like `https://the-origin/the/current/path/foo`.
     * `frameName` string - Name of the window provided in `window.open()`
     * `features` string - Comma separated list of window features provided to `window.open()`.
-    * `disposition` string - Can be `default`, `foreground-tab`, `background-tab`,
-      `new-window` or `other`.
+    * `disposition` string - Can be `default`, `foreground-tab`,
+      `background-tab`, `new-window` or `other`. Corresponds to the manner
+      an associated link was clicked. See Chromium's
+      [WindowOpenDisposition](https://source.chromium.org/chromium/chromium/src/+/main:ui/base/window_open_disposition.h).
+      * `default` - Indicates Chromium deems in-window navigation valid
+        for a window open call.
+      * `foreground-tab` - Corresponds to a left click or shift + middle click.
+      * `background-tab` - Corresponds to a middle click or ctrl/cmd + click.
+      * `new-window` - Corresponds to a shift + left click.
+      * `other` - A catch-all for the remaining Chromium dispositions not
+        handled by Electron.
     * `referrer` [Referrer](structures/referrer.md) - The referrer that will be
       passed to the new window. May or may not result in the `Referer` header being
       sent, depending on the referrer policy.