openFile

Category: Dialog Operations

Namespace: web.dialogs.openFile

Description

Display a native Windows Open File dialog that allows users to browse and select one or more files from their computer. Returns the full path to the selected file as a string, or an array of full paths when multiSelect: true is used. Returns null if the user cancels.

Syntax

// Single file (default)
const filePath = await web.dialogs.openFile({
    title: string,
    fileName: string,
    fileTypes: string
});

// Multiple files
const filePaths = await web.dialogs.openFile({
    title: string,
    fileName: string,
    fileTypes: string,
    multiSelect: true
});

Parameters

• title (optional) - Dialog window title. Default: "Open File"
• fileName (optional) - Default filename to show in the dialog. Default: ""
• fileTypes (optional) - File type filter string in format: "Description|*.ext|Description2|*.ext2". Default: "All Files|*.*"
• multiSelect (optional) - When true, allows selecting multiple files. Returns an array of paths instead of a string. Default: false

Returns

• Without multiSelect — Promise<string> — Full path to selected file, or null if user cancelled
• With multiSelect: true — Promise<string[]> — Array of full paths to selected files, or null if user cancelled

Examples

Simple example — single file

const filePath = await web.dialogs.openFile();

if (filePath) {
    console.log('Selected:', filePath);
}

Open a text file for editing

const filePath = await web.dialogs.openFile({
    title: 'Open Text File',
    fileTypes: 'Text Files|*.txt|All Files|*.*'
});

if (filePath) {
    const content = await web.files.readTextFile({ filePath });
    document.getElementById('editor').value = content;
} else {
    console.log('User cancelled');
}

Multiple file selection

const filePaths = await web.dialogs.openFile({
    title: 'Open Images',
    fileTypes: 'Images|*.jpg;*.jpeg;*.png;*.gif;*.bmp;*.webp',
    multiSelect: true
});

if (!filePaths) return; // cancelled

console.log(`Selected ${filePaths.length} file(s)`);
filePaths.forEach(p => console.log(' -', p));

Advanced — multi-type dialog with cancel check

const filePath = await web.dialogs.openFile({
    title: 'Open Document',
    fileName: 'document.json',
    fileTypes: 'JSON Files|*.json|Text Files|*.txt|XML Files|*.xml|All Files|*.*'
});

if (!filePath) return; // user cancelled

const extension = filePath.split('.').pop().toLowerCase();

if (extension === 'json') {
    const content = await web.files.readTextFile({ filePath });
    const data = JSON.parse(content);
    loadJsonData(data);
} else if (extension === 'txt') {
    const content = await web.files.readTextFile({ filePath });
    displayTextContent(content);
}

Use Cases

• Let users select a file to open in your application
• Browse for configuration or data files
• Select images or media files to load
• Multi-select for batch processing (resize images, convert files, etc.)
• Replace HTML <input type="file"> with a native dialog
• File picker for any file operation

Error Handling

Returns null if the user cancels. Always check before proceeding.

const filePath = await web.dialogs.openFile({ title: 'Select File' });

if (!filePath) {
    console.log('No file selected');
    return;
}

const content = await web.files.readTextFile({ filePath });

For multiSelect, the return is also null on cancel (not an empty array):

const paths = await web.dialogs.openFile({ multiSelect: true });

if (!paths) return; // cancelled — paths is null, not []

Related Methods

• web.dialogs.saveFile() - Save file dialog
• web.dialogs.selectFolder() - Folder selection dialog
• web.files.readTextFile() - Read a selected text file
• web.files.readFileAsBase64() - Read a selected binary file (images, PDFs, etc.)
• web.files.fileExists() - Check if a file exists

Notes

• Native Windows dialog — not an HTML <input type="file">
• Returns full absolute paths (e.g. C:\Users\Alice\Documents\file.txt)
• Returns null on cancel (not empty string, not empty array)
• File type filter format: "Description|*.ext|Description2|*.ext2"
• Multiple extensions in one filter: "Images|*.jpg;*.png;*.gif"
• multiSelect: true — returns string[]; omitting it (or false) returns string
• Backwards compatible — existing code without multiSelect is unaffected
• Dialog remembers the last used directory
• User can navigate to any accessible location