docs/src/content/docs/reference/dialogs.mdx
import { Card, CardGrid } from "@astrojs/starlight/components";
The Dialogs API provides methods to show native file dialogs and message dialogs. Access dialogs through the app.Dialog manager.
Dialog Types:
All dialogs are native OS dialogs that match the platform's look and feel.
Dialogs are accessed through the app.Dialog manager:
app.Dialog.OpenFile()
app.Dialog.SaveFile()
app.Dialog.Info()
app.Dialog.Question()
app.Dialog.Warning()
app.Dialog.Error()
Creates a file open dialog.
func (dm *DialogManager) OpenFile() *OpenFileDialogStruct
Example:
dialog := app.Dialog.OpenFile()
Sets the dialog title.
func (d *OpenFileDialogStruct) SetTitle(title string) *OpenFileDialogStruct
Example:
dialog.SetTitle("Select Image")
Adds a file type filter.
func (d *OpenFileDialogStruct) AddFilter(displayName, pattern string) *OpenFileDialogStruct
Parameters:
displayName - Filter description shown to user (e.g., "Images", "Documents")pattern - Semicolon-separated list of extensions (e.g., ".png;.jpg")Example:
dialog.AddFilter("Images", "*.png;*.jpg;*.gif").
AddFilter("Documents", "*.pdf;*.docx").
AddFilter("All Files", "*.*")
Sets the initial directory.
func (d *OpenFileDialogStruct) SetDirectory(directory string) *OpenFileDialogStruct
Example:
homeDir, _ := os.UserHomeDir()
dialog.SetDirectory(homeDir)
Enables or disables directory selection.
func (d *OpenFileDialogStruct) CanChooseDirectories(canChooseDirectories bool) *OpenFileDialogStruct
Example (folder selection):
// Select folders instead of files
path, err := app.Dialog.OpenFile().
SetTitle("Select Folder").
CanChooseDirectories(true).
CanChooseFiles(false).
PromptForSingleSelection()
Enables or disables file selection.
func (d *OpenFileDialogStruct) CanChooseFiles(canChooseFiles bool) *OpenFileDialogStruct
Enables or disables creating new directories.
func (d *OpenFileDialogStruct) CanCreateDirectories(canCreateDirectories bool) *OpenFileDialogStruct
Shows or hides hidden files.
func (d *OpenFileDialogStruct) ShowHiddenFiles(showHiddenFiles bool) *OpenFileDialogStruct
Attaches the dialog to a specific window.
func (d *OpenFileDialogStruct) AttachToWindow(window Window) *OpenFileDialogStruct
Shows the dialog and returns the selected file.
func (d *OpenFileDialogStruct) PromptForSingleSelection() (string, error)
Returns:
string - Selected file path. Treat an empty string as "no selection" (the platform impls may return either an empty string or a non-nil error on cancellation depending on OS).error - Non-nil if the dialog itself failed to present.Example:
path, err := app.Dialog.OpenFile().
SetTitle("Select Image").
AddFilter("Images", "*.png;*.jpg;*.gif").
PromptForSingleSelection()
if err != nil {
// The dialog failed to present (rare).
return
}
if path == "" {
// User cancelled.
return
}
// Use the selected file
processFile(path)
Shows the dialog and returns multiple selected files.
func (d *OpenFileDialogStruct) PromptForMultipleSelection() ([]string, error)
Returns:
[]string - Array of selected file pathserror - Error if dialog failedExample:
paths, err := app.Dialog.OpenFile().
SetTitle("Select Images").
AddFilter("Images", "*.png;*.jpg").
PromptForMultipleSelection()
if err != nil {
return
}
for _, path := range paths {
processFile(path)
}
Creates a file save dialog.
func (dm *DialogManager) SaveFile() *SaveFileDialogStruct
Example:
dialog := app.Dialog.SaveFile()
Sets the dialog title.
func (d *SaveFileDialogStruct) SetTitle(title string) *SaveFileDialogStruct
Sets the default filename.
func (d *SaveFileDialogStruct) SetFilename(filename string) *SaveFileDialogStruct
Example:
dialog.SetFilename("document.pdf")
Adds a file type filter.
func (d *SaveFileDialogStruct) AddFilter(displayName, pattern string) *SaveFileDialogStruct
Example:
dialog.AddFilter("PDF Document", "*.pdf").
AddFilter("Text Document", "*.txt")
Sets the initial directory.
func (d *SaveFileDialogStruct) SetDirectory(directory string) *SaveFileDialogStruct
Attaches the dialog to a specific window.
func (d *SaveFileDialogStruct) AttachToWindow(window Window) *SaveFileDialogStruct
Shows the dialog and returns the save path.
func (d *SaveFileDialogStruct) PromptForSingleSelection() (string, error)
Example:
path, err := app.Dialog.SaveFile().
SetTitle("Save Document").
SetFilename("untitled.pdf").
AddFilter("PDF Document", "*.pdf").
PromptForSingleSelection()
if err != nil {
// User cancelled
return
}
// Save to the selected path
saveDocument(path)
There is no separate SelectFolderDialog. Use OpenFile() with directory options:
path, err := app.Dialog.OpenFile().
SetTitle("Select Output Folder").
CanChooseDirectories(true).
CanChooseFiles(false).
PromptForSingleSelection()
if err != nil {
// User cancelled
return
}
// Use the selected folder
outputDir = path
All message dialogs return *MessageDialog and share the same methods.
Creates an information dialog.
func (dm *DialogManager) Info() *MessageDialog
Example:
app.Dialog.Info().
SetTitle("Success").
SetMessage("File saved successfully!").
Show()
Creates an error dialog.
func (dm *DialogManager) Error() *MessageDialog
Example:
app.Dialog.Error().
SetTitle("Error").
SetMessage("Failed to save file: " + err.Error()).
Show()
Creates a warning dialog.
func (dm *DialogManager) Warning() *MessageDialog
Example:
app.Dialog.Warning().
SetTitle("Warning").
SetMessage("This action cannot be undone.").
Show()
Creates a question dialog with custom buttons.
func (dm *DialogManager) Question() *MessageDialog
Example:
dialog := app.Dialog.Question().
SetTitle("Confirm").
SetMessage("Do you want to save changes?")
save := dialog.AddButton("Save")
save.OnClick(func() {
saveDocument()
})
dontSave := dialog.AddButton("Don't Save")
dontSave.OnClick(func() {
// Continue without saving
})
cancel := dialog.AddButton("Cancel")
cancel.OnClick(func() {
// Do nothing
})
dialog.SetDefaultButton(save)
dialog.SetCancelButton(cancel)
dialog.Show()
Sets the dialog title.
func (d *MessageDialog) SetTitle(title string) *MessageDialog
Sets the dialog message.
func (d *MessageDialog) SetMessage(message string) *MessageDialog
Sets a custom icon for the dialog.
func (d *MessageDialog) SetIcon(icon []byte) *MessageDialog
Adds a button to the dialog and returns the button for configuration.
func (d *MessageDialog) AddButton(label string) *Button
Returns: *Button - The button instance for further configuration
Example:
button := dialog.AddButton("OK")
button.OnClick(func() {
// Handle click
})
Sets which button is the default (activated by pressing Enter).
func (d *MessageDialog) SetDefaultButton(button *Button) *MessageDialog
Example:
yes := dialog.AddButton("Yes")
no := dialog.AddButton("No")
dialog.SetDefaultButton(yes)
Sets which button is the cancel button (activated by pressing Escape).
func (d *MessageDialog) SetCancelButton(button *Button) *MessageDialog
Example:
ok := dialog.AddButton("OK")
cancel := dialog.AddButton("Cancel")
dialog.SetCancelButton(cancel)
Attaches the dialog to a specific window.
func (d *MessageDialog) AttachToWindow(window Window) *MessageDialog
Shows the dialog. Button callbacks handle user responses.
func (d *MessageDialog) Show()
Note: Show() does not return a value. Use button callbacks to handle user responses.
Sets the callback function for when the button is clicked.
func (b *Button) OnClick(callback func()) *Button
Marks this button as the default button.
func (b *Button) SetAsDefault() *Button
Marks this button as the cancel button.
func (b *Button) SetAsCancel() *Button
type FileService struct {
app *application.App
}
func (s *FileService) OpenImage() (string, error) {
path, err := s.app.Dialog.OpenFile().
SetTitle("Select Image").
AddFilter("Images", "*.png;*.jpg;*.jpeg;*.gif").
AddFilter("All Files", "*.*").
PromptForSingleSelection()
if err != nil {
return "", err
}
return path, nil
}
func (s *FileService) SaveDocument(defaultName string) (string, error) {
path, err := s.app.Dialog.SaveFile().
SetTitle("Save Document").
SetFilename(defaultName).
AddFilter("PDF Document", "*.pdf").
AddFilter("Text Document", "*.txt").
PromptForSingleSelection()
if err != nil {
return "", err
}
return path, nil
}
func (s *FileService) SelectOutputFolder() (string, error) {
path, err := s.app.Dialog.OpenFile().
SetTitle("Select Output Folder").
CanChooseDirectories(true).
CanChooseFiles(false).
PromptForSingleSelection()
if err != nil {
return "", err
}
return path, nil
}
func (s *Service) DeleteItem(app *application.App, id string) {
dialog := app.Dialog.Question().
SetTitle("Confirm Delete").
SetMessage("Are you sure you want to delete this item?")
deleteBtn := dialog.AddButton("Delete")
deleteBtn.OnClick(func() {
deleteFromDatabase(id)
})
cancelBtn := dialog.AddButton("Cancel")
// Cancel does nothing
dialog.SetDefaultButton(cancelBtn) // Default to Cancel for safety
dialog.SetCancelButton(cancelBtn)
dialog.Show()
}
func (s *Editor) PromptSaveChanges(app *application.App) {
dialog := app.Dialog.Question().
SetTitle("Unsaved Changes").
SetMessage("Do you want to save your changes before closing?")
save := dialog.AddButton("Save")
save.OnClick(func() {
s.Save()
s.Close()
})
dontSave := dialog.AddButton("Don't Save")
dontSave.OnClick(func() {
s.Close()
})
cancel := dialog.AddButton("Cancel")
// Cancel does nothing, dialog closes
dialog.SetDefaultButton(save)
dialog.SetCancelButton(cancel)
dialog.Show()
}
func (s *Service) ProcessMultipleFiles(app *application.App) error {
// Select multiple files
paths, err := app.Dialog.OpenFile().
SetTitle("Select Files to Process").
AddFilter("Images", "*.png;*.jpg").
PromptForMultipleSelection()
if err != nil {
return err
}
if len(paths) == 0 {
app.Dialog.Info().
SetTitle("No Files Selected").
SetMessage("Please select at least one file.").
Show()
return nil
}
// Process files
for _, path := range paths {
err := processFile(path)
if err != nil {
app.Dialog.Error().
SetTitle("Processing Error").
SetMessage(fmt.Sprintf("Failed to process %s: %v", path, err)).
Show()
continue
}
}
// Show completion
app.Dialog.Info().
SetTitle("Complete").
SetMessage(fmt.Sprintf("Successfully processed %d files", len(paths))).
Show()
return nil
}
func (s *Service) SaveFile(app *application.App, data []byte) error {
// Select save location
path, err := app.Dialog.SaveFile().
SetTitle("Save File").
SetFilename("data.json").
AddFilter("JSON File", "*.json").
PromptForSingleSelection()
if err != nil {
// User cancelled - not an error
return nil
}
// Attempt to save
err = os.WriteFile(path, data, 0644)
if err != nil {
// Show error dialog
app.Dialog.Error().
SetTitle("Save Failed").
SetMessage(fmt.Sprintf("Could not save file: %v", err)).
Show()
return err
}
// Show success
app.Dialog.Info().
SetTitle("Success").
SetMessage("File saved successfully!").
Show()
return nil
}
import (
"os"
"path/filepath"
"runtime"
)
func (s *Service) GetDefaultDirectory() string {
homeDir, _ := os.UserHomeDir()
switch runtime.GOOS {
case "windows":
return filepath.Join(homeDir, "Documents")
case "darwin":
return filepath.Join(homeDir, "Documents")
case "linux":
return filepath.Join(homeDir, "Documents")
default:
return homeDir
}
}
func (s *Service) OpenWithDefaults(app *application.App) (string, error) {
return app.Dialog.OpenFile().
SetTitle("Open File").
SetDirectory(s.GetDefaultDirectory()).
AddFilter("All Files", "*.*").
PromptForSingleSelection()
}
On Linux, the default GTK4 build uses xdg-desktop-portal for file dialogs, which provides
native desktop integration but means some options have no effect. The legacy GTK3 path
(-tags gtk3) retains full programmatic control over these options:
| Option | GTK3 (-tags gtk3) | GTK4 (default) | Notes |
|---|---|---|---|
ShowHiddenFiles() | ✅ Works | ❌ No effect | User controls via dialog's UI toggle (Ctrl+H or menu) |
CanCreateDirectories() | ✅ Works | ❌ No effect | Always enabled in the portal |
ResolvesAliases() | ✅ Works | ❌ No effect | Portal handles symlink resolution |
SetButtonText() | ✅ Works | ✅ Works | Custom accept button text works |
Why these limitations exist: GTK4's portal-based dialogs delegate UI control to the desktop environment (GNOME, KDE, etc.). This is by design — the portal provides consistent UX across applications and respects user preferences.
:::note
The default GTK4 build uses the portal-backed dialogs. If your application needs full
programmatic control over the dialog options above, build with the legacy -tags gtk3 path
(supported through v3.0.x; removed in v3.1) — see Linux Packaging - Legacy GTK3 Support.
:::
func (s *Service) SaveAs(app *application.App, currentPath string) (string, error) {
// Extract filename from current path
filename := filepath.Base(currentPath)
// Show save dialog
path, err := app.Dialog.SaveFile().
SetTitle("Save As").
SetFilename(filename).
PromptForSingleSelection()
if err != nil {
return "", err
}
return path, nil
}
func (s *Service) OpenRecent(app *application.App, recentPath string) error {
// Check if file still exists
if _, err := os.Stat(recentPath); os.IsNotExist(err) {
dialog := app.Dialog.Question().
SetTitle("File Not Found").
SetMessage("The file no longer exists. Remove from recent files?")
remove := dialog.AddButton("Remove")
remove.OnClick(func() {
s.removeFromRecent(recentPath)
})
cancel := dialog.AddButton("Cancel")
dialog.SetCancelButton(cancel)
dialog.Show()
return err
}
return s.openFile(recentPath)
}