diff --git a/docs/api/dialog.md b/docs/api/dialog.md
index 870ba685a1a0..45d0a794c216 100644
--- a/docs/api/dialog.md
+++ b/docs/api/dialog.md
@@ -117,6 +117,9 @@ The `filters` specifies an array of file types that can be displayed, see
 If a `callback` is passed, the API call will be asynchronous and the result
 will be passed via `callback(filename)`.
 
+**Note:** On macOS, using the `callback` is recommended to avoid issues when
+expanding and collapsing the dialog.
+
 ### `dialog.showMessageBox([browserWindow, ]options[, callback])`
 
 * `browserWindow` [BrowserWindow](browser-window.md) (optional)