diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
index 57d71da59cdb..53ed57f0c389 100644
--- a/docs/api/browser-window.md
+++ b/docs/api/browser-window.md
@@ -410,9 +410,10 @@ window.onbeforeunload = (e) => {
   // a non-void value will silently cancel the close.
   // It is recommended to use the dialog API to let the user confirm closing the
   // application.
-  e.returnValue = false
+  e.returnValue = false // equivalent to `return false` but not recommended
 }
 ```
+_**Note**: There is a subtle difference between the behaviors of `window.onbeforeunload = handler` and `window.addEventListener('beforeunload', handler)`. It is recommended to always set the `event.returnValue` explicitly, instead of just returning a value, as the former works more consistently within Electron._
 
 #### Event: 'closed'