FolderPicker

Modal dialog for browsing and selecting a folder.

Overview

FolderPicker extends Window and presents a modal dialog for browsing the filesystem and selecting a directory. Unlike FilePicker, only directories are displayed in the listing. Use Up/Down to navigate, Enter to descend into a directory, Space to select the currently highlighted directory, Backspace to navigate to the parent directory, and Escape to cancel without selecting. The control supports an IFileSystem abstraction for testing and virtualized file sources.

Basic Example

<FolderPicker Title="Select Folder"
              InitialDirectory="/home/user" />

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 folder after confirmation, or null if cancelled.
Title	string	"Select Folder"	The title displayed in the dialog header.

Static API

// Show the folder picker and await the result
string? selectedFolder = await FolderPicker.ShowAsync(
    initialDirectory: "/home/user/projects",
    fileSystem: null  // uses real filesystem by default
);

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

The ShowAsync method creates a FolderPicker 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

Simple Folder Selection

<FolderPicker Title="Choose Output Directory"
              InitialDirectory="/home/user/projects" />

Using ShowAsync in Code-Behind

private async Task OnSelectFolderClicked()
{
    var folder = await FolderPicker.ShowAsync(
        initialDirectory: Environment.GetFolderPath(
            Environment.SpecialFolder.MyDocuments)
    );

    if (folder is not null)
    {
        ViewModel.OutputDirectory = folder;
    }
}

With Custom IFileSystem for Testing

var mockFs = new MockFileSystem(new Dictionary<string, string[]>
{
    ["/root"] = ["docs", "src", "tests"],
    ["/root/src"] = ["app", "lib"]
});

var folder = await FolderPicker.ShowAsync(
    initialDirectory: "/root",
    fileSystem: mockFs
);

Keyboard Shortcuts

Key	Action
Up Arrow	Move selection to the previous directory.
Down Arrow	Move selection to the next directory.
Enter	Navigate into the selected directory.
Space	Select the currently highlighted directory 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 directories in real-time.
Click	Select the clicked directory entry.
Double-click	Navigate into the clicked directory.
Scroll wheel	Move selection up or down.

Key Concepts

FolderPicker extends Window and displays as a modal dialog over the current application content.
Only directories are listed; files are not shown, keeping the view focused on folder selection.
Enter navigates into a directory, while Space selects the highlighted directory as the result.
The SelectedPath property contains the full path to the chosen folder after confirmation, or null if the user cancels.
Use the static FolderPicker.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, providing familiar filesystem navigation.
Press / to activate fuzzy search. Type to filter directories — characters are matched in order but don't need to be contiguous. Press Escape to exit search, or Enter to navigate into a match.
Mouse support: click to select a row, double-click to navigate into a directory, scroll wheel to move the selection.