19 KiB
dialog
Display native system dialogs for opening and saving files, alerting, etc.
Process: Main
An example of showing a dialog to select multiple files:
const { dialog } = require('electron')
console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))
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:
const { dialog } = require('electron').remote
console.log(dialog)
Methods
The dialog
module has the following methods:
dialog.showOpenDialogSync([browserWindow, ]options)
browserWindow
BrowserWindow (optional)options
Objecttitle
String (optional)defaultPath
String (optional)buttonLabel
String (optional) - Custom label for the confirmation button, when left empty the default label will be used.filters
FileFilter[] (optional)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.createDirectory
macOS - Allow creating new directories from dialog.promptToCreate
Windows - Prompt for creation if the file path entered 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 created by the application.noResolveAliases
macOS - Disable the automatic alias (symlink) path resolution. Selected aliases will now return the alias path instead of their target path.treatPackageAsDirectory
macOS - Treat packages, such as.app
folders, as a directory instead of a file.dontAddToRecent
Windows - Do not add the item being opened to the recent documents list.
message
String (optional) macOS - Message to display above input boxes.securityScopedBookmarks
Boolean (optional) macOS mas - Create security scoped bookmarks when packaged for the Mac App Store.
The browserWindow
argument allows the dialog to attach itself to a parent window, making it modal.
The filters
specifies an array of file types that can be displayed or
selected when you want to limit the user to a specific type. For example:
{
filters: [
{ name: 'Images', extensions: ['jpg', 'png', 'gif'] },
{ name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
{ name: 'Custom File Type', extensions: ['as'] },
{ name: 'All Files', extensions: ['*'] }
]
}
The extensions
array should contain extensions without wildcards or dots (e.g.
'png'
is good but '.png'
and '*.png'
are bad). To show all files, use the
'*'
wildcard (no other wildcard is supported).
Note: On Windows and Linux an open dialog can not be both a file selector
and a directory selector, so if you set properties
to
['openFile', 'openDirectory']
on these platforms, a directory selector will be
shown.
dialog.showOpenDialogSync(mainWindow, {
properties: ['openFile', 'openDirectory']
})
dialog.showOpenDialog([browserWindow, ]options)
browserWindow
BrowserWindow (optional)options
Objecttitle
String (optional)defaultPath
String (optional)buttonLabel
String (optional) - Custom label for the confirmation button, when left empty the default label will be used.filters
FileFilter[] (optional)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.createDirectory
macOS - Allow creating new directories from dialog.promptToCreate
Windows - Prompt for creation if the file path entered 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 created by the application.noResolveAliases
macOS - Disable the automatic alias (symlink) path resolution. Selected aliases will now return the alias path instead of their target path.treatPackageAsDirectory
macOS - Treat packages, such as.app
folders, as a directory instead of a file.dontAddToRecent
Windows - Do not add the item being opened to the recent documents list.
message
String (optional) macOS - Message to display above input boxes.securityScopedBookmarks
Boolean (optional) macOS mas - Create security scoped bookmarks when packaged for the Mac App Store.
Returns Promise<Object>
- Resolve with an object containing the following:
canceled
Boolean - whether or not the dialog was canceled.filePaths
String[] - An array of file paths chosen by the user. If the dialog is cancelled this will be an empty array.bookmarks
String[] (optional) macOS mas - An array matching thefilePaths
array of base64 encoded strings which contains security scoped bookmark data.securityScopedBookmarks
must be enabled for this to be populated.
The browserWindow
argument allows the dialog to attach itself to a parent window, making it modal.
The filters
specifies an array of file types that can be displayed or
selected when you want to limit the user to a specific type. For example:
{
filters: [
{ name: 'Images', extensions: ['jpg', 'png', 'gif'] },
{ name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
{ name: 'Custom File Type', extensions: ['as'] },
{ name: 'All Files', extensions: ['*'] }
]
}
The extensions
array should contain extensions without wildcards or dots (e.g.
'png'
is good but '.png'
and '*.png'
are bad). To show all files, use the
'*'
wildcard (no other wildcard is supported).
Note: On Windows and Linux an open dialog can not be both a file selector
and a directory selector, so if you set properties
to
['openFile', 'openDirectory']
on these platforms, a directory selector will be
shown.
dialog.showOpenDialog(mainWindow, {
properties: ['openFile', 'openDirectory']
}).then(result => {
console.log(result.canceled)
console.log(result.filePaths)
}).catch(err => {
console.log(err)
})
dialog.showSaveDialogSync([browserWindow, ]options)
browserWindow
BrowserWindow (optional)options
Objecttitle
String (optional)defaultPath
String (optional) - Absolute directory path, absolute file path, or file name to use by default.buttonLabel
String (optional) - Custom label for the confirmation button, when left empty the default label will be used.filters
FileFilter[] (optional)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 totrue
.properties
String[] (optional)showHiddenFiles
- Show hidden files in dialog.createDirectory
macOS - Allow creating new directories from dialog.treatPackageAsDirectory
macOS - Treat packages, such as.app
folders, as a directory instead of a file.showOverwriteConfirmation
Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.dontAddToRecent
Windows - Do not add the item being saved to the recent documents list.
securityScopedBookmarks
Boolean (optional) macOS mas - Create a security scoped bookmark 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.
Returns String | undefined
, the path of the file chosen by the user; if the dialog is cancelled it returns undefined
.
The browserWindow
argument allows the dialog to attach itself to a parent window, making it modal.
The filters
specifies an array of file types that can be displayed, see
dialog.showOpenDialog
for an example.
dialog.showSaveDialog([browserWindow, ]options)
browserWindow
BrowserWindow (optional)options
Objecttitle
String (optional)defaultPath
String (optional) - Absolute directory path, absolute file path, or file name to use by default.buttonLabel
String (optional) - Custom label for the confirmation button, when left empty the default label will be used.filters
FileFilter[] (optional)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 totrue
.properties
String[] (optional)showHiddenFiles
- Show hidden files in dialog.createDirectory
macOS - Allow creating new directories from dialog.treatPackageAsDirectory
macOS - Treat packages, such as.app
folders, as a directory instead of a file.showOverwriteConfirmation
Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.dontAddToRecent
Windows - Do not add the item being saved to the recent documents list.
securityScopedBookmarks
Boolean (optional) macOS mas - Create a security scoped bookmark 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.
Returns Promise<Object>
- Resolve with an object containing the following:
canceled
Boolean - whether or not the dialog was canceled.filePath
String (optional) - If the dialog is canceled, this will beundefined
.bookmark
String (optional) 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.
The browserWindow
argument allows the dialog to attach itself to a parent window, making it modal.
The filters
specifies an array of file types that can be displayed, see
dialog.showOpenDialog
for an example.
Note: On macOS, using the asynchronous version is recommended to avoid issues when expanding and collapsing the dialog.
dialog.showMessageBoxSync([browserWindow, ]options)
browserWindow
BrowserWindow (optional)options
Objecttype
String (optional) - Can be"none"
,"info"
,"error"
,"question"
or"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.buttons
String[] (optional) - Array of texts for buttons. On Windows, an empty array will result in one button labeled "OK".defaultId
Integer (optional) - Index of the button in the buttons array which will be selected by default when the message box opens.title
String (optional) - Title of the message box, some platforms will not show it.message
String - Content of the message box.detail
String (optional) - Extra information of the message.checkboxLabel
String (optional) - If provided, the message box will include a checkbox with the given label.checkboxChecked
Boolean (optional) - Initial checked state of the checkbox.false
by default.icon
NativeImage (optional)cancelId
Integer (optional) - The index of the button to be used to cancel the dialog, via theEsc
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 return value.noLink
Boolean (optional) - On Windows Electron will try to figure out which one of thebuttons
are common buttons (like "Cancel" or "Yes"), and show the others as command links in the dialog. This can make the dialog appear in the style of modern Windows apps. If you don't like this behavior, you can setnoLink
totrue
.normalizeAccessKeys
Boolean (optional) - Normalize the keyboard access keys across platforms. Default isfalse
. 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 ofVie&w
will be converted toVie_w
on Linux andView
on macOS and can be selected viaAlt-W
on Windows and Linux.
Returns Integer
- the index of the clicked button.
Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button.
The browserWindow
argument allows the dialog to attach itself to a parent window, making it modal.
dialog.showMessageBox([browserWindow, ]options)
browserWindow
BrowserWindow (optional)options
Objecttype
String (optional) - Can be"none"
,"info"
,"error"
,"question"
or"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.buttons
String[] (optional) - Array of texts for buttons. On Windows, an empty array will result in one button labeled "OK".defaultId
Integer (optional) - Index of the button in the buttons array which will be selected by default when the message box opens.title
String (optional) - Title of the message box, some platforms will not show it.message
String - Content of the message box.detail
String (optional) - Extra information of the message.checkboxLabel
String (optional) - If provided, the message box will include a checkbox with the given label.checkboxChecked
Boolean (optional) - Initial checked state of the checkbox.false
by default.icon
NativeImage (optional)cancelId
Integer (optional) - The index of the button to be used to cancel the dialog, via theEsc
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 return value.noLink
Boolean (optional) - On Windows Electron will try to figure out which one of thebuttons
are common buttons (like "Cancel" or "Yes"), and show the others as command links in the dialog. This can make the dialog appear in the style of modern Windows apps. If you don't like this behavior, you can setnoLink
totrue
.normalizeAccessKeys
Boolean (optional) - Normalize the keyboard access keys across platforms. Default isfalse
. 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 ofVie&w
will be converted toVie_w
on Linux andView
on macOS and can be selected viaAlt-W
on Windows and Linux.
Returns Promise<Object>
- resolves with a promise containing the following properties:
response
Number - The index of the clicked button.checkboxChecked
Boolean - The checked state of the checkbox ifcheckboxLabel
was set. Otherwisefalse
.
Shows a message box, it will block the process until the message box is closed.
The browserWindow
argument allows the dialog to attach itself to a parent window, making it modal.
dialog.showErrorBox(title, content)
title
String - The title to display in the error box.content
String - The text content to display in the error box.
Displays a modal dialog that shows an error message.
This API can be called safely before the ready
event the app
module emits,
it is usually used to report errors in early stage of startup. If called
before the app ready
event on Linux, the message will be emitted to stderr,
and no GUI dialog will appear.
dialog.showCertificateTrustDialog([browserWindow, ]options)
macOS Windows
browserWindow
BrowserWindow (optional)options
Objectcertificate
Certificate - The certificate to trust/import.message
String - The message to display to the user.
Returns Promise<void>
- resolves when the certificate trust dialog is shown.
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
attached to the parent window, making it modal.
On Windows the options are more limited, due to the Win32 APIs used:
- The
message
argument is not used, as the OS provides its own confirmation dialog. - The
browserWindow
argument is ignored since it is not possible to make this confirmation dialog modal.
Sheets
On macOS, dialogs are presented as sheets attached to a window if you provide
a BrowserWindow
reference in the browserWindow
parameter, or modals if no
window is provided.
You can call BrowserWindow.getCurrentWindow().setSheetOffset(offset)
to change
the offset from the window frame where sheets are attached.