diff --git a/docs/latest/api/browser-window.md b/docs/latest/api/browser-window.md
index 67e63bf..6b193c3 100644
--- a/docs/latest/api/browser-window.md
+++ b/docs/latest/api/browser-window.md
@@ -999,6 +999,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'](latest/api/browser-window.md#event-enter-full-screen) or ['leave-full-screen'](latest/api/browser-window.md#event-leave-full-screen) events.
+
 #### `win.isFullScreen()`
 
 Returns `boolean` - Whether the window is in fullscreen mode.