2013-09-09 07:35:57 +00:00
# dialog
2013-08-14 22:43:35 +00:00
2016-04-21 22:39:12 +00:00
> Display native system dialogs for opening and saving files, alerting, etc.
2013-08-14 22:43:35 +00:00
2016-11-23 19:20:56 +00:00
Process: [Main ](../glossary.md#main-process )
2016-11-03 17:26:00 +00:00
2013-08-14 22:43:35 +00:00
An example of showing a dialog to select multiple files and directories:
```javascript
2018-09-13 16:10:51 +00:00
const { dialog } = require('electron')
console.log(dialog.showOpenDialog({ properties: ['openFile', 'openDirectory', 'multiSelections'] }))
2013-08-14 22:43:35 +00:00
```
2016-04-22 13:53:26 +00:00
The Dialog is opened from Electron's main thread. If you want to use the dialog
object from a renderer process, remember to access it using the remote:
2016-03-31 16:54:01 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { dialog } = require('electron').remote
2016-07-26 01:39:25 +00:00
console.log(dialog)
2016-03-31 16:54:01 +00:00
```
2015-08-25 12:46:06 +00:00
## Methods
2013-08-14 22:43:35 +00:00
2015-08-25 12:46:06 +00:00
The `dialog` module has the following methods:
2015-12-17 10:40:52 +00:00
### `dialog.showOpenDialog([browserWindow, ]options[, callback])`
2015-08-25 12:46:06 +00:00
2017-11-29 10:38:35 +00:00
* `browserWindow` [BrowserWindow ](browser-window.md ) (optional)
2015-12-17 10:40:52 +00:00
* `options` Object
2016-11-05 08:42:45 +00:00
* `title` String (optional)
2016-10-30 10:46:20 +00:00
* `defaultPath` String (optional)
* `buttonLabel` String (optional) - Custom label for the confirmation button, when
2016-05-16 01:09:41 +00:00
left empty the default label will be used.
2016-11-20 15:49:11 +00:00
* `filters` [FileFilter[]](structures/file-filter.md) (optional)
2017-02-02 16:30:02 +00:00
* `properties` String[] (optional) - Contains which features the dialog should
use. The following values are supported:
* `openFile` - Allow files to be selected.
* `openDirectory` - Allow directories to be selected.
* `multiSelections` - Allow multiple paths to be selected.
* `showHiddenFiles` - Show hidden files in dialog.
2017-11-29 10:38:35 +00:00
* `createDirectory` _macOS_ - Allow creating new directories from dialog.
* `promptToCreate` _Windows_ - Prompt for creation if the file path entered
2017-02-02 16:30:02 +00:00
in the dialog does not exist. This does not actually create the file at
the path but allows non-existent paths to be returned that should be
2017-11-29 10:38:35 +00:00
created by the application.
* `noResolveAliases` _macOS_ - Disable the automatic alias (symlink) path
2017-11-29 10:58:24 +00:00
resolution. Selected aliases will now return the alias path instead of
2017-11-29 10:38:35 +00:00
their target path.
* `treatPackageAsDirectory` _macOS_ - Treat packages, such as `.app` folders,
as a directory instead of a file.
2017-03-31 22:08:03 +00:00
* `message` String (optional) _macOS_ - Message to display above input
boxes.
2018-02-12 18:48:45 +00:00
* `securityScopedBookmarks` Boolean (optional) _masOS_ _mas_ - Create [security scoped bookmarks ](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16 ) when packaged for the Mac App Store.
2015-08-25 12:46:06 +00:00
* `callback` Function (optional)
2016-10-13 06:30:57 +00:00
* `filePaths` String[] - An array of file paths chosen by the user
2018-02-12 18:25:06 +00:00
* `bookmarks` String[] _macOS_ _mas_ - An array matching the `filePaths` array of base64 encoded strings which contains security scoped bookmark data. `securityScopedBookmarks` must be enabled for this to be populated.
2013-08-14 22:43:35 +00:00
2016-11-05 08:42:45 +00:00
Returns `String[]` , an array of file paths chosen by the user,
if the callback is provided it returns `undefined` .
2013-08-14 22:43:35 +00:00
2016-12-07 04:23:14 +00:00
The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
2014-08-06 07:00:31 +00:00
The `filters` specifies an array of file types that can be displayed or
2015-08-25 12:46:06 +00:00
selected when you want to limit the user to a specific type. For example:
2014-08-06 07:00:31 +00:00
2016-08-16 21:50:21 +00:00
```javascript
2014-08-06 07:00:31 +00:00
{
filters: [
2018-09-13 16:10:51 +00:00
{ name: 'Images', extensions: ['jpg', 'png', 'gif'] },
{ name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
{ name: 'Custom File Type', extensions: ['as'] },
{ name: 'All Files', extensions: ['*'] }
2015-06-09 15:59:53 +00:00
]
2014-08-06 07:00:31 +00:00
}
```
2015-09-02 01:19:18 +00:00
2015-08-22 02:09:37 +00:00
The `extensions` array should contain extensions without wildcards or dots (e.g.
2015-08-25 12:46:06 +00:00
`'png'` is good but `'.png'` and `'*.png'` are bad). To show all files, use the
2015-08-22 02:09:37 +00:00
`'*'` wildcard (no other wildcard is supported).
2014-08-06 07:00:31 +00:00
2015-08-25 12:46:06 +00:00
If a `callback` is passed, the API call will be asynchronous and the result
2017-11-29 10:38:35 +00:00
will be passed via `callback(filenames)` .
2014-03-13 06:09:30 +00:00
2015-08-26 23:41:25 +00:00
**Note:** On Windows and Linux an open dialog can not be both a file selector
2015-06-07 19:32:54 +00:00
and a directory selector, so if you set `properties` to
2015-08-22 02:09:37 +00:00
`['openFile', 'openDirectory']` on these platforms, a directory selector will be
shown.
2013-08-14 22:43:35 +00:00
2015-12-17 10:40:52 +00:00
### `dialog.showSaveDialog([browserWindow, ]options[, callback])`
2013-08-14 22:43:35 +00:00
2017-11-29 10:38:35 +00:00
* `browserWindow` [BrowserWindow ](browser-window.md ) (optional)
2015-12-17 10:40:52 +00:00
* `options` Object
2016-11-05 08:42:45 +00:00
* `title` String (optional)
2017-05-25 23:11:58 +00:00
* `defaultPath` String (optional) - Absolute directory path, absolute file
path, or file name to use by default.
2016-10-30 10:46:20 +00:00
* `buttonLabel` String (optional) - Custom label for the confirmation button, when
2016-05-16 01:09:41 +00:00
left empty the default label will be used.
2016-12-13 08:42:47 +00:00
* `filters` [FileFilter[]](structures/file-filter.md) (optional)
2017-02-09 19:29:10 +00:00
* `message` String (optional) _macOS_ - Message to display above text fields.
* `nameFieldLabel` String (optional) _macOS_ - Custom label for the text
displayed in front of the filename text field.
* `showsTagField` Boolean (optional) _macOS_ - Show the tags input box,
defaults to `true` .
2018-02-12 18:25:06 +00:00
* `securityScopedBookmarks` Boolean (optional) _masOS_ _mas_ - Create a [security scoped bookmark ](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16 ) when packaged for the Mac App Store. If this option is enabled and the file doesn't already exist a blank file will be created at the chosen path.
2015-08-25 12:46:06 +00:00
* `callback` Function (optional)
2016-10-13 06:30:57 +00:00
* `filename` String
2018-02-12 18:25:06 +00:00
* `bookmark` String _macOS_ _mas_ - Base64 encoded string which contains the security scoped bookmark data for the saved file. `securityScopedBookmarks` must be enabled for this to be present.
2013-08-14 22:43:35 +00:00
2016-11-05 08:42:45 +00:00
Returns `String` , the path of the file chosen by the user,
if a callback is provided it returns `undefined` .
2013-08-14 22:43:35 +00:00
2016-12-07 04:23:14 +00:00
The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
2014-08-06 07:00:31 +00:00
The `filters` specifies an array of file types that can be displayed, see
`dialog.showOpenDialog` for an example.
2015-06-07 19:32:54 +00:00
If a `callback` is passed, the API call will be asynchronous and the result
2017-11-29 10:38:35 +00:00
will be passed via `callback(filename)` .
2013-08-14 22:43:35 +00:00
2015-12-17 10:40:52 +00:00
### `dialog.showMessageBox([browserWindow, ]options[, callback])`
2013-08-14 22:43:35 +00:00
2017-11-29 10:38:35 +00:00
* `browserWindow` [BrowserWindow ](browser-window.md ) (optional)
2015-12-17 10:40:52 +00:00
* `options` Object
2016-10-30 10:46:20 +00:00
* `type` String (optional) - Can be `"none"` , `"info"` , `"error"` , `"question"` or
2017-04-13 18:36:48 +00:00
`"warning"` . On Windows, `"question"` displays the same icon as `"info"` , unless
you set an icon using the `"icon"` option. On macOS, both `"warning"` and
`"error"` display the same warning icon.
2016-12-29 22:11:26 +00:00
* `buttons` String[] (optional) - Array of texts for buttons. On Windows, an empty array
2016-05-19 09:32:43 +00:00
will result in one button labeled "OK".
2016-10-30 10:46:20 +00:00
* `defaultId` Integer (optional) - Index of the button in the buttons array which will
2016-01-11 03:15:40 +00:00
be selected by default when the message box opens.
2016-10-30 10:46:20 +00:00
* `title` String (optional) - Title of the message box, some platforms will not show it.
2015-08-25 12:46:06 +00:00
* `message` String - Content of the message box.
2016-10-30 10:46:20 +00:00
* `detail` String (optional) - Extra information of the message.
2017-02-06 15:35:36 +00:00
* `checkboxLabel` String (optional) - If provided, the message box will
include a checkbox with the given label. The checkbox state can be
inspected only when using `callback` .
* `checkboxChecked` Boolean (optional) - Initial checked state of the
checkbox. `false` by default.
2016-10-30 10:46:20 +00:00
* `icon` [NativeImage ](native-image.md ) (optional)
2017-02-24 23:56:47 +00:00
* `cancelId` Integer (optional) - The index of the button to be used to cancel the dialog, via
the `Esc` key. By default this is assigned to the first button with "cancel" or "no" as the
label. If no such labeled buttons exist and this option is not set, `0` will be used as the
2018-08-10 06:07:39 +00:00
return value or callback response.
2016-10-30 10:46:20 +00:00
* `noLink` Boolean (optional) - On Windows Electron will try to figure out which one of
2015-07-23 09:20:43 +00:00
the `buttons` are common buttons (like "Cancel" or "Yes"), and show the
2015-08-25 12:46:06 +00:00
others as command links in the dialog. This can make the dialog appear in
2015-07-23 09:20:43 +00:00
the style of modern Windows apps. If you don't like this behavior, you can
2015-08-25 12:46:06 +00:00
set `noLink` to `true` .
2017-03-31 22:08:03 +00:00
* `normalizeAccessKeys` Boolean (optional) - Normalize the keyboard access keys
across platforms. Default is `false` . Enabling this assumes `&` is used in
the button labels for the placement of the keyboard shortcut access key
and labels will be converted so they work correctly on each platform, `&`
characters are removed on macOS, converted to `_` on Linux, and left
untouched on Windows. For example, a button label of `Vie&w` will be
converted to `Vie_w` on Linux and `View` on macOS and can be selected
via `Alt-W` on Windows and Linux.
2016-11-05 08:42:45 +00:00
* `callback` Function (optional)
2017-11-29 10:38:35 +00:00
* `response` Number - The index of the button that was clicked.
2017-02-06 15:35:36 +00:00
* `checkboxChecked` Boolean - The checked state of the checkbox if
`checkboxLabel` was set. Otherwise `false` .
2013-08-14 22:43:35 +00:00
2016-11-05 08:42:45 +00:00
Returns `Integer` , the index of the clicked button, if a callback is provided
it returns undefined.
2015-08-25 12:46:06 +00:00
Shows a message box, it will block the process until the message box is closed.
It returns the index of the clicked button.
2013-08-14 22:43:35 +00:00
2016-12-07 04:23:14 +00:00
The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
2017-05-08 08:41:16 +00:00
If a `callback` is passed, the dialog will not block the process. The API call
will be asynchronous and the result will be passed via `callback(response)` .
2015-01-05 05:56:45 +00:00
2015-08-25 12:46:06 +00:00
### `dialog.showErrorBox(title, content)`
2015-01-05 05:56:45 +00:00
2017-11-29 10:38:35 +00:00
* `title` String - The title to display in the error box.
* `content` String - The text content to display in the error box.
2016-08-25 17:52:19 +00:00
2015-08-25 12:46:06 +00:00
Displays a modal dialog that shows an error message.
2015-01-05 05:56:45 +00:00
2015-08-25 12:46:06 +00:00
This API can be called safely before the `ready` event the `app` module emits,
2017-11-29 10:58:24 +00:00
it is usually used to report errors in early stage of startup. If called
2015-11-12 13:20:09 +00:00
before the app `ready` event on Linux, the message will be emitted to stderr,
2015-10-31 23:04:01 +00:00
and no GUI dialog will appear.
2016-03-27 01:12:25 +00:00
2017-04-21 03:09:49 +00:00
### `dialog.showCertificateTrustDialog([browserWindow, ]options, callback)` _macOS_ _Windows_
2017-04-03 19:39:45 +00:00
2017-11-29 10:38:35 +00:00
* `browserWindow` [BrowserWindow ](browser-window.md ) (optional)
2017-04-04 01:33:21 +00:00
* `options` Object
* `certificate` [Certificate ](structures/certificate.md ) - The certificate to trust/import.
* `message` String - The message to display to the user.
2017-04-03 19:39:45 +00:00
* `callback` Function
2017-04-27 05:12:30 +00:00
On macOS, this displays a modal dialog that shows a message and certificate
information, and gives the user the option of trusting/importing the
certificate. If you provide a `browserWindow` argument the dialog will be
2017-04-29 09:35:49 +00:00
attached to the parent window, making it modal.
2017-04-03 19:39:45 +00:00
2017-04-27 05:12:30 +00:00
On Windows the options are more limited, due to the Win32 APIs used:
2017-04-29 09:35:49 +00:00
- The `message` argument is not used, as the OS provides its own confirmation
2017-04-27 05:12:30 +00:00
dialog.
2017-04-29 09:35:49 +00:00
- The `browserWindow` argument is ignored since it is not possible to make
this confirmation dialog modal.
2017-04-04 17:49:10 +00:00
2016-03-27 01:12:25 +00:00
## Sheets
2016-06-18 13:26:26 +00:00
On macOS, dialogs are presented as sheets attached to a window if you provide
2017-11-29 10:38:35 +00:00
a [`BrowserWindow` ](browser-window.md ) reference in the `browserWindow` parameter, or modals if no
2016-03-27 01:12:25 +00:00
window is provided.
2016-04-19 05:39:12 +00:00
You can call `BrowserWindow.getCurrentWindow().setSheetOffset(offset)` to change
the offset from the window frame where sheets are attached.