Table of Contents
- Overview
- Methods
- 🧊 Task<MessageBoxResult> ShowMessageBoxAsync(BrowserWindow browserWindow, MessageBoxOptions messageBoxOptions)
- 🧊 Task<MessageBoxResult> ShowMessageBoxAsync(BrowserWindow browserWindow, string message)
- 🧊 Task<MessageBoxResult> ShowMessageBoxAsync(MessageBoxOptions messageBoxOptions)
- 🧊 Task<MessageBoxResult> ShowMessageBoxAsync(string message)
- 🧊 Task<string[]> ShowOpenDialogAsync(BrowserWindow browserWindow, OpenDialogOptions options)
- 🧊 Task<string> ShowSaveDialogAsync(BrowserWindow browserWindow, SaveDialogOptions options)
- 🧊 void ShowErrorBox(string title, string content)
- 🧊 Task ShowCertificateTrustDialogAsync(BrowserWindow browserWindow, CertificateTrustDialogOptions options)
- 🧊 Task ShowCertificateTrustDialogAsync(CertificateTrustDialogOptions options)
- Usage Examples
- Related APIs
- Additional Resources
Display native system dialogs for opening and saving files, alerting, etc.
Overview
The Electron.Dialog API provides access to native system dialogs for file operations, message boxes, and certificate trust dialogs. These dialogs are modal and provide a consistent user experience across different platforms.
Methods
🧊 Task<MessageBoxResult> ShowMessageBoxAsync(BrowserWindow browserWindow, MessageBoxOptions messageBoxOptions)
Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button. If a callback is passed, the dialog will not block the process.
Parameters:
browserWindow- The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.messageBoxOptions- Message content and configuration
Returns:
The API call will be asynchronous and the result will be passed via MessageBoxResult.
🧊 Task<MessageBoxResult> ShowMessageBoxAsync(BrowserWindow browserWindow, string message)
Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button. If a callback is passed, the dialog will not block the process.
Parameters:
browserWindow- The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.message- Message content
Returns:
The API call will be asynchronous and the result will be passed via MessageBoxResult.
🧊 Task<MessageBoxResult> ShowMessageBoxAsync(MessageBoxOptions messageBoxOptions)
Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button. If a callback is passed, the dialog will not block the process.
Parameters:
messageBoxOptions- Message content and configuration
Returns:
The API call will be asynchronous and the result will be passed via MessageBoxResult.
🧊 Task<MessageBoxResult> ShowMessageBoxAsync(string message)
Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button. If a callback is passed, the dialog will not block the process.
Parameters:
message- Message content
Returns:
The API call will be asynchronous and the result will be passed via MessageBoxResult.
🧊 Task<string[]> ShowOpenDialogAsync(BrowserWindow browserWindow, OpenDialogOptions options)
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.
Parameters:
browserWindow- The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.options- Dialog configuration options
Returns:
An array of file paths chosen by the user
🧊 Task<string> ShowSaveDialogAsync(BrowserWindow browserWindow, SaveDialogOptions options)
Dialog for save files.
Parameters:
browserWindow- The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.options- Dialog configuration options
Returns:
Returns String, the path of the file chosen by the user, if a callback is provided it returns an empty string.
🧊 void ShowErrorBox(string title, string content)
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 readyevent on Linux, the message will be emitted to stderr, and no GUI dialog will appear.
Parameters:
title- The title to display in the error box.content- The text content to display in the error box.
🧊 Task ShowCertificateTrustDialogAsync(BrowserWindow browserWindow, CertificateTrustDialogOptions options)
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.
Parameters:
browserWindow- Parent window for modal behavioroptions- Certificate trust dialog options
🧊 Task ShowCertificateTrustDialogAsync(CertificateTrustDialogOptions options)
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.
Parameters:
options- Certificate trust dialog options
Usage Examples
File Operations
// Open multiple files
var files = await Electron.Dialog.ShowOpenDialogAsync(window, new OpenDialogOptions
{
Properties = new[] { OpenDialogProperty.OpenFile, OpenDialogProperty.MultiSelections }
});
// Save with custom extension
var path = await Electron.Dialog.ShowSaveDialogAsync(window, new SaveDialogOptions
{
DefaultPath = "backup.json",
Filters = new[] { new FileFilter { Name = "JSON", Extensions = new[] { "json" } } }
});
User Confirmation
// Confirmation dialog
var result = await Electron.Dialog.ShowMessageBoxAsync(window, new MessageBoxOptions
{
Type = MessageBoxType.Question,
Title = "Confirm Delete",
Message = $"Delete {filename}?",
Buttons = new[] { "Cancel", "Delete" },
DefaultId = 0,
CancelId = 0
});
if (result.Response == 1)
{
// Delete file
}
Error Handling
// Error dialog
Electron.Dialog.ShowErrorBox("Save Failed", "Could not save file. Please check permissions and try again.");
// Warning dialog
await Electron.Dialog.ShowMessageBoxAsync(new MessageBoxOptions
{
Type = MessageBoxType.Warning,
Title = "Warning",
Message = "This operation may take several minutes.",
Buttons = new[] { "Continue", "Cancel" }
});
Related APIs
- Electron.WindowManager - Parent windows for modal dialogs
- Electron.App - Application lifecycle events
- Electron.Shell - File operations with selected paths
Additional Resources
- Electron Dialog Documentation - Official Electron dialog API
- API Overview
- Electron.App
- Electron.Dialog
- Electron.Menu
- Electron.WindowManager
- Electron.Shell
- Electron.Screen
- Electron.Notification
- Electron.Tray
- Electron.Clipboard
- Electron.Dock
- Electron.HostHook
- Electron.IpcMain
- Electron.GlobalShortcut
- Electron.AutoUpdater
- Electron.NativeTheme
- Electron.PowerMonitor
Want to contribute to this documentation? Please fork and create a PR! The Wiki is autogenerated from the /docs content in the repository.