diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
index 5c87398106..2b47cd13ca 100644
--- a/docs/api/browser-window.md
+++ b/docs/api/browser-window.md
@@ -992,6 +992,8 @@ Returns `boolean` - Whether the window is minimized.
 
 Sets whether the window should be in fullscreen mode.
 
+**Note:** On macOS, fullscreen transitions take place asynchronously. If further actions depend on the fullscreen state, use the ['enter-full-screen'](browser-window.md#event-enter-full-screen) or ['leave-full-screen'](browser-window.md#event-leave-full-screen) events.
+
 #### `win.isFullScreen()`
 
 Returns `boolean` - Whether the window is in fullscreen mode.