Skip to content

About

A TreeView component for WinUI 3 that is specifically designed to parse paths.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

BetterPathTreeview for WinUI 3

NuGet License: MIT GitHub Platform WinUI 3 Windows App SDK

A lazy-loading and better WinUI 3 TreeView custom control for navigating filesystem paths and virtual hierarchies such as ZIP archives, FTP listings, or any custom data source.


Screenshots

Filesystem — all drives Filesystem view — all drives, expand any drive to lazy-load its subfolders

Filesystem — hidden folders Hidden and system folders shown at 50% opacity

Virtual ZIP provider ZIP archive structure exposed as a navigable tree via VirtualTreeNodeProvider


Features

  • Lazy loading — children are fetched on demand when the user expands a node; no full scan at startup
  • Filesystem provider — browses all drives or a specific root path; optional hidden and system folder display with automatic dimmed opacity
  • Virtual provider — builds a navigable tree from any flat list of slash-separated paths (ZIP entries, FTP listings, database hierarchies…)
  • Custom provider — implement ITreeNodeProvider to connect any data source
  • Path reveal — RevealPathAsync(path) programmatically expands and scrolls to any path
  • Reload — ReloadAsync() refreshes the entire tree without disposing the control
  • Search / filter — built-in AutoSuggestBox with real-time node filtering (virtual provider) or configurable behaviour
  • Custom icons — per-node icon, control-level RootIcon / NodeIcon override; accepts Segoe Fluent Icons glyph, PNG, or SVG
  • Tooltip — full path shown on hover for every node
  • Hidden folder dimming — nodes with IsHidden = true are rendered at 50% opacity via BoolToOpacityConverter
  • MIT licensed

Requirements

Requirement Minimum version
.NET 9.0
Windows 10 version 1809 (build 17763)
Windows App SDK 1.8
Target framework net9.0-windows10.0.19041.0

Installation

dotnet add package BetterPathTreeview_WinUI3

Or search for BetterPathTreeview_WinUI3 in the Visual Studio NuGet Package Manager.


Quick start

1 — Add namespaces to your XAML

xmlns:ctrl="using:BetterPathTreeview.Control"

2 — Create a provider in code-behind

// All drives
public FileSystemTreeNodeProvider FsProvider { get; } =
    new FileSystemTreeNodeProvider();

// Rooted at a path, showing hidden and system folders
public FileSystemTreeNodeProvider FsProvider { get; } =
    new FileSystemTreeNodeProvider(@"C:\Users", showHidden: true);

// Virtual tree from ZIP entries
var (provider, root) = VirtualTreeNodeProvider.FromPaths(
    zipFile.Entries.Select(e => e.FullName),
    rootName: "archive.zip");

3 — Add the control to your page

<ctrl:BetterPathTreeview
    x:Name="MyTreeview"
    NodeProvider="{x:Bind FsProvider}"
    ShowSearchBox="True"
    NodeSelected="OnNodeSelected"
    NodeExpanded="OnNodeExpanded"
    NodeInvoked="OnNodeInvoked"/>

4 — Handle events

private void OnNodeSelected(object sender, TreeNodeEventArgs e)
{
    // e.Path  → full path string
    // e.Node  → TreeNode object
    MyStatusBar.Text = e.Path;
}

private void OnNodeExpanded(object sender, TreeNodeEventArgs e)
{
    Debug.WriteLine($"Expanded: {e.Path}");
}

private void OnNodeInvoked(object sender, TreeNodeEventArgs e)
{
    // double-click or Enter key
    OpenFolder(e.Path);
}

XAML API reference

Dependency properties

Property Type Default Description
NodeProvider ITreeNodeProvider null Data source for the tree
ShowSearchBox bool true Show or hide the search/filter box
RootIcon string? null Icon override for all root nodes (glyph or image path)
NodeIcon string? null Icon override for all non-root nodes

Read-only properties

Property Type Description
SelectedNode TreeNode? Currently selected node

Events

Event Args type Fired when
NodeSelected TreeNodeEventArgs User clicks a node
NodeExpanded TreeNodeEventArgs User expands a node
NodeInvoked TreeNodeEventArgs User double-clicks or presses Enter on a node

Methods

// Expand and scroll to a path in the tree
await myTreeview.RevealPathAsync(@"C:\Windows\System32");

// Full tree reload (keeps provider, discards loaded nodes)
await myTreeview.ReloadAsync();

Providers

FileSystemTreeNodeProvider

Reads the Windows filesystem lazily. Files are never shown — only folders.

// All drives ("This PC" view)
var provider = new FileSystemTreeNodeProvider();

// Rooted at a specific path
var provider = new FileSystemTreeNodeProvider(@"C:\Projects");

// Show hidden and system folders (rendered at 50% opacity)
var provider = new FileSystemTreeNodeProvider(showHidden: true);

// Rooted + show hidden
var provider = new FileSystemTreeNodeProvider(@"C:\Users", showHidden: true);

Hidden/system folders are included when showHidden: true and are automatically shown at 50% opacity thanks to BoolToOpacityConverter in the control's DataTemplate.

VirtualTreeNodeProvider

Builds a navigable folder tree from a flat list of slash-separated paths.

string[] entries =
[
    "2024/01/",
    "2024/02/",
    "2024/02/report.xml",
    "2025/01/backup.zip",
];

var (provider, root) = VirtualTreeNodeProvider.FromPaths(
    entries,
    rootName: "my-archive.zip");

MyTreeview.NodeProvider = provider;

Only the folder structure is exposed. File entries are used to infer folder structure but are not displayed as nodes unless includeFiles: true is passed.

Custom provider

Implement ITreeNodeProvider to connect any data source:

public class FtpTreeProvider : ITreeNodeProvider
{
    private readonly FtpClient _client;

    public FtpTreeProvider(FtpClient client) => _client = client;

    public bool SupportsSearch => false; // lazy remote source

    public async Task<IEnumerable<TreeNode>> GetRootsAsync(CancellationToken ct = default)
    {
        return new[]
        {
            new TreeNode { Name = "ftp://myserver", FullPath = "/", IsRoot = true }
        };
    }

    public async Task<IEnumerable<TreeNode>> GetChildrenAsync(
        TreeNode node, CancellationToken ct = default)
    {
        var dirs = await _client.ListDirectoriesAsync(node.FullPath, ct);
        return dirs.Select(d => new TreeNode
        {
            Name     = d.Name,
            FullPath = d.FullPath,
            IsLeaf   = !d.HasSubdirectories
        });
    }
}

TreeNode model

Property Type Description
Name string Display name shown in the node label
FullPath string Full path (filesystem or virtual) — also used for reveal and tooltips
IsRoot bool Root node — rendered with drive icon by default
IsLeaf bool No children — chevron is hidden
IsHidden bool Rendered at 50% opacity (hidden/system folders)
Icon string? Per-node icon: Segoe Fluent Icons glyph, .png path, or .svg path
Children List<TreeNode> Pre-loaded children (used by virtual provider)
Tag object? Arbitrary host data, not used by the control

Custom icons

Icons are resolved in this order (first non-null wins):

  1. TreeNode.Icon — per-node override
  2. NodeIcon / RootIcon dependency property — control-level override
  3. Built-in default — drive glyph (\uEDA2) for roots, folder glyph (\uE8B7) for all others

Accepted formats:

// Segoe Fluent Icons glyph
node.Icon = "\uE8B7";

// Absolute path to PNG or SVG
node.Icon = @"C:\MyApp\Assets\folder-special.png";

// ms-appx URI
node.Icon = "ms-appx:///Assets/folder-special.svg";

Switching provider at runtime

When the user changes an option (e.g. "Show hidden"), create a new provider and assign it:

private void ShowHidden_Changed(object sender, RoutedEventArgs e)
{
    bool showHidden = sender is CheckBox cb && cb.IsChecked == true;
    FsTreeview.NodeProvider = new FileSystemTreeNodeProvider(showHidden: showHidden);
}

Assigning a new NodeProvider automatically triggers a full reload.


Changelog

See CHANGELOG.md.


License

MIT — see LICENSE for details.


Author

Matteo Riso — zipgenius.it
Written with Claude AI by Anthropic.

About

A TreeView component for WinUI 3 that is specifically designed to parse paths.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages