The Dialog API allows you to display native file and folder selection dialogs, with support for filters, multiple selections, and save dialogs.
Basic Usage
use Native\Desktop\Dialog;
// Open file dialog
$filePath = Dialog::new()
->title('Select a file')
->open();
// Save file dialog
$savePath = Dialog::new()
->title('Save file as')
->save();
Creating Dialogs
new
Create a new dialog instance.
Returns a new Dialog instance
Configuration Methods
title
Set the dialog window title.
The title text for the dialog window
Returns the Dialog instance for method chaining
$dialog->title('Select a configuration file');
defaultPath
Set the default path where the dialog opens.
The default directory or file path
Returns the Dialog instance for method chaining
$dialog->defaultPath(storage_path('exports'));
The text for the button (default is “Select”)
Returns the Dialog instance for method chaining
$dialog->button('Choose File');
files
Configure the dialog to select files.
Returns the Dialog instance for method chaining
folders
Configure the dialog to select folders/directories.
Returns the Dialog instance for method chaining
multiple
Allow selection of multiple files or folders.
Returns the Dialog instance for method chaining
withHiddenFiles
Show hidden files in the dialog.
Returns the Dialog instance for method chaining
$dialog->withHiddenFiles();
dontResolveSymlinks
Prevent the dialog from resolving symbolic links.
Returns the Dialog instance for method chaining
$dialog->dontResolveSymlinks();
filter
Add a file type filter to the dialog.
The display name for the filter (e.g., “Images”)
Array of file extensions without dots (e.g., [“jpg”, “png”])
Returns the Dialog instance for method chaining
$dialog->filter('Images', ['jpg', 'jpeg', 'png', 'gif']);
properties
Set custom dialog properties directly.
Array of property strings (e.g., [“openFile”, “multiSelections”])
Returns the Dialog instance for method chaining
$dialog->properties(['openFile', 'multiSelections']);
openFile - Allow file selectionopenDirectory - Allow directory selectionmultiSelections - Allow multiple selectionsshowHiddenFiles - Show hidden filesnoResolveAliases - Don’t resolve symbolic links
asSheet
Display the dialog as a sheet attached to a window (macOS only).
The window ID to attach to (defaults to current window)
Returns the Dialog instance for method chaining
// Attach to current window
$dialog->asSheet();
// Attach to specific window
$dialog->asSheet('main-window');
Dialog Actions
open
Open the dialog and return the selected path(s).
Returns the selected path (string) for single selection, array of paths for multiple selection, or null if cancelled
// Single file selection
$file = Dialog::new()->open();
// Multiple file selection
$files = Dialog::new()->multiple()->open();
save
Open a save dialog and return the selected path.
Returns the selected save path or null if cancelled
$savePath = Dialog::new()
->title('Save export as')
->defaultPath(storage_path('exports/data.csv'))
->save();
Examples
Select a Single File
use Native\Desktop\Dialog;
$filePath = Dialog::new()
->title('Select a PDF file')
->filter('PDF Files', ['pdf'])
->open();
if ($filePath) {
// Process the file
}
Select Multiple Images
use Native\Desktop\Dialog;
$images = Dialog::new()
->title('Select images to import')
->filter('Images', ['jpg', 'jpeg', 'png', 'gif', 'webp'])
->multiple()
->open();
foreach ($images as $image) {
// Process each image
}
Select a Folder
use Native\Desktop\Dialog;
$folder = Dialog::new()
->title('Choose project directory')
->folders()
->open();
Save File Dialog
use Native\Desktop\Dialog;
$savePath = Dialog::new()
->title('Export data')
->button('Export')
->defaultPath(storage_path('exports/data.csv'))
->filter('CSV Files', ['csv'])
->save();
if ($savePath) {
file_put_contents($savePath, $csvData);
}
Multiple File Types Filter
use Native\Desktop\Dialog;
$file = Dialog::new()
->title('Select a document')
->filter('Documents', ['pdf', 'doc', 'docx'])
->filter('Spreadsheets', ['xls', 'xlsx', 'csv'])
->filter('All Files', ['*'])
->open();
Dialog as Sheet (macOS)
use Native\Desktop\Dialog;
use Native\Desktop\Facades\Window;
$file = Dialog::new()
->title('Open file')
->asSheet()
->open();
Advanced Configuration
use Native\Desktop\Dialog;
$files = Dialog::new()
->title('Import configuration files')
->defaultPath(config_path())
->button('Import')
->filter('JSON Files', ['json'])
->filter('YAML Files', ['yml', 'yaml'])
->multiple()
->withHiddenFiles()
->open();
if (!empty($files)) {
foreach ($files as $file) {
// Import each configuration file
}
}