FilePicker

Modal dialog for browsing and selecting files from the filesystem.

Overview

FilePicker extends Window and presents a modal dialog for browsing the filesystem and selecting a file. Directories are displayed with a folder icon and files are listed below them. Use Up/Down to navigate the list, Enter to open a directory or select a file, Backspace to navigate to the parent directory, and Escape to cancel without selecting. An optional Filter property restricts the visible files (e.g., "*.txt"). The control supports an IFileSystem abstraction for testing and virtualized file sources.

Basic Example

<FilePicker Title="Select File"
            InitialDirectory="/home/user/documents"
            Filter="*.txt" />

Properties

Property	Type	Default	Description
InitialDirectory	string	Current directory	The directory to display when the picker opens.
SelectedPath	string?	null	The full path of the selected file after confirmation, or null if cancelled.
Filter	string?	null	Glob pattern to filter visible files (e.g., `".txt"`, `".cs"`). Directories are always shown.
Title	string	"Select File"	The title displayed in the dialog header.

Static API

// Show the file picker and await the result
string? selectedFile = await FilePicker.ShowAsync(
    initialDirectory: "/home/user/documents",
    filter: "*.txt",
    fileSystem: null  // uses real filesystem by default
);

if (selectedFile is not null)
{
    Console.WriteLine($"Selected: {selectedFile}");
}

The ShowAsync method creates a FilePicker window, displays it modally, and returns the SelectedPath once the user confirms or null if cancelled. Pass a custom IFileSystem implementation for unit testing.

Examples

Unfiltered File Browser

<FilePicker Title="Open File"
            InitialDirectory="/home/user" />

Filtered by Extension

<FilePicker Title="Select Image"
            InitialDirectory="/home/user/pictures"
            Filter="*.png" />

Using ShowAsync in Code-Behind

private async Task OnOpenFileClicked()
{
    var path = await FilePicker.ShowAsync(
        initialDirectory: Environment.GetFolderPath(
            Environment.SpecialFolder.MyDocuments),
        filter: "*.cs"
    );

    if (path is not null)
    {
        ViewModel.FilePath = path;
    }
}

Keyboard Shortcuts

Key	Action
Up Arrow	Move selection to the previous entry.
Down Arrow	Move selection to the next entry.
Enter	Open the selected directory, or select the highlighted file and close the dialog.
Backspace	Navigate to the parent directory (or delete last character in search mode).
Escape	Exit search mode, or cancel the dialog and return null.
/	Activate fuzzy search — type to filter entries in real-time. Matches characters in order (not necessarily contiguous). Results are ranked by consecutive matches and word-boundary hits.
Click	Select the clicked entry.
Double-click	Open the clicked directory, or select the clicked file.
Scroll wheel	Move selection up or down.

Key Concepts

FilePicker extends Window and displays as a modal dialog over the current application content.
Directories are shown with a folder icon and are always visible regardless of the Filter setting.
Files are filtered by the Filter glob pattern when specified; all files are shown when Filter is null.
The SelectedPath property contains the full path to the chosen file after confirmation, or null if the user cancels.
Use the static FilePicker.ShowAsync method for a one-call pattern that returns the selected path directly.
Pass a custom IFileSystem implementation to ShowAsync for unit testing without real filesystem access.
Pressing Backspace navigates up to the parent directory, while Enter on a directory descends into it.
Press / to activate fuzzy search. Type to filter entries — characters are matched in order but don't need to be contiguous. Results are ranked by consecutive runs and word-boundary hits. Press Escape to exit search, or Enter to select from filtered results.