Add docs for useNativeWindowOpen

docs/api/browser-window.md

@@ -295,6 +295,7 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
       'Electron Isolated Context' entry in the combo box at the top of the
       Console tab. **Note:** This option is currently experimental and may
       change or be removed in future Electron releases.
+    * `useNativeWindowOpen` Boolean (optional) - Whether to use native `window.open()`.
 
 When setting minimum or maximum window size with `minWidth`/`maxWidth`/
 `minHeight`/`maxHeight`, it only constrains the users. It won't prevent you from

docs/api/window-open.md

@@ -41,3 +41,27 @@ has to be a field of `BrowserWindow`'s options.
 
 Sends a message to the parent window with the specified origin or `*` for no
 origin preference.
+
+### Use Native `window.open()`
+
+If you want to use native `window.open()` implementation, pass `useNativeWindowOpen: true` in `webPreferences` option.
+Native `window.open()` allows synchronous access to opened windows so it is convenient choise if you need to open a dialog or a preferences window.
+
+The creation of the `BrowserWindow` is customizable in `WebContents`'s `new-window` event.
+
+```javascript
+mainWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures) => {
+  if (url.endsWith("modal.html")) {
+    // open window as modal
+    event.preventDefault()
+    Object.assign(options, {
+      modal: true,
+      parent: mainWindow,
+      width: 100,
+      height: 100
+    })
+    modal = new BrowserWindow(options)
+    modal.loadURL(url)
+    event.newGuest = modal
+  }
+```