Add file explorer modal

[baldwindavid]

Update: 12/15/2025 - Per #44530 (comment) holding on this one until that PR lands. Maintainers feel free to close as needed for now.

Summary

Adds a new file explorer modal that provides hierarchical directory navigation as an alternative to the fuzzy file finder, open path prompt, and project panel. This allows users to browse files directory-by-directory with focused, contextual navigation - appearing in the center of the screen rather than in a persistent sidebar.

Motivation

Zed offers several existing ways to navigate files:

• Fuzzy file finder: Great for jumping to known files by name
• Open path prompt: Filesystem-wide path browser for opening files anywhere
• Project panel: Persistent sidebar showing the full directory tree

However, each has limitations:

• The fuzzy finder requires knowing the file name
• The open path prompt uses absolute paths and isn't contextual to your current location
• The project panel requires looking away from your code to the left sidebar, breaks visual flow, takes persistent space, and can be disorienting with many directories expanded

What's missing: A way to hierarchically browse files that's contextual (starts where you are), focused (one directory at a time), and centered (doesn't require looking to a sidebar).

Inspiration from Vim's netrw:
Many Vim users appreciate netrw's approach of opening a file browser in the current context. While a full in-pane implementation doesn't fit Zed's architecture, the modal file explorer captures the essence of this workflow: quick, contextual, hierarchical navigation without leaving your working area.

This feature provides an additional navigation option that combines strengths from existing tools: hierarchical browsing like the project panel, modal presentation like the file finder, and contextual starting point based on your current file.

Features

Core Functionality

• Hierarchical navigation: Browse one directory at a time, navigate into/out of subdirectories
• Smart opening: Opens to the current file's parent directory with the file pre-selected
• Multi-worktree support: When multiple worktrees are open, navigate between them via a worktree selection view
• Visual clarity: Full path displayed in filter placeholder (e.g., "Filter project-name/src/components")

UI & Interaction

• Directory sorting: Directories listed before files, each group sorted alphabetically
• Case-insensitive filtering: Type to filter entries by substring match
• Parent navigation: ".." entry to navigate up (shown in subdirectories)
• Worktree navigation: "All Worktrees" entry at worktree root (when multiple worktrees exist) navigates to worktree selection view
• Smart context: Opens to current file's directory, or worktree selection when no file is active with multiple worktrees
• Split support: Open files in split panes via split menu
• Preview tabs: Respects enable_preview_from_file_explorer setting

Usage

Trigger via file_explorer::Toggle action (no default keybinding). The modal can be dismissed normally, and submenus (filter/split) properly prevent dismissal when focused.

Multi-worktree workflow:

1. Open file explorer in a project with multiple worktrees
2. If no file is active, worktree selection view is shown automatically
3. At a worktree root, "All Worktrees" entry appears to navigate back to selection
4. Select a worktree to navigate into it
5. Navigate files/directories as normal within that worktree

Actions

• file_explorer::Toggle - Open/close the file explorer
• file_explorer::NavigateToParent - Navigate to parent directory
• file_explorer::ToggleFilterMenu - Toggle filter options
• file_explorer::ToggleSplitMenu - Toggle split menu

Implementation Notes

• New crate: file_explorer
• Reuses Picker component with custom delegate
• Integrates with existing preview tabs system
• Follows file finder patterns for consistency (filter menu, split menu, focus handling)

Alternative Approaches Considered

Enhanced Open Prompt

Initially explored adding an "Open in Current Directory" feature to the existing open prompt (workspace::Open). This would have allowed the file path picker to default to the current file's directory with preselection.

Why not chosen:

• The open prompt is designed for absolute path navigation and cross-worktree browsing
• Adding directory-relative behavior would complicate the existing picker's logic
• Doesn't provide the hierarchical, directory-focused browsing experience
• Would mix two different navigation paradigms in one interface

In-Pane Navigation (netrw-style)

Explored implementing an in-pane file browser similar to Vim's netrw, where the browser would replace the current editor pane and allow navigation within the pane itself.

Why not chosen:

• Conflicts with Zed's modal-focused navigation pattern (file finder, command palette, etc.)
• Would require significant changes to pane management and item lifecycle
• Less discoverable - users would need to learn a new pane type
• Modal approach is more familiar to VS Code users and fits existing Zed patterns

The modal approach fits naturally with Zed's existing navigation patterns, doesn't disrupt workspace layout, and includes multi-worktree support through a hierarchical selection view - allowing access to all worktrees without needing a persistent panel.

External TUI File Manager (e.g., Yazi)

An existing workaround involves launching a TUI file manager like Yazi via Zed's terminal and task system (see discussion #9067). This provides a powerful, vim-style file browsing experience through custom keybindings and wrapper scripts.

However, this approach has significant limitations:

• Not built-in: Requires users to install and configure an external tool, raising the barrier to entry
• No remote support: TUI file managers launched in the terminal don't work when connected to remote projects, as the terminal runs on the remote host while file opening needs to occur in the local Zed instance
• Integration friction: Seamless workflows (e.g., opening files in the current pane, preview tabs, split opening) require custom wrapper scripts and workarounds rather than working out of the box
• Inconsistent UX: The terminal-based UI doesn't match Zed's native look and feel or respect Zed's theming

A built-in modal provides a consistent, zero-configuration experience that works across local and remote contexts.

Future Considerations

• Settings Support: Similar to the file_finder, settings for modal_max_width, file_icons, etc. could be added later.
• File Actions: The ability to crud directories and files via this explorer could be considered, but is far too much for now.
• Live Preview: I originally had a setting to allow for live preview of files when tabbing/arrowing over files, but pulled that out to limit the additions. Live preview is something I'd like to see in a number of pickers, but should be approached separately and holistically.

Screencasts

Basic Navigation

Multi-Worktree Support

Release Notes:

• Added file explorer modal for hierarchical directory navigation with multi-worktree support

[yara-blue]

Could you explain why this should be its own picker vs the existing file finder? Are we missing a key option on the file finder?

[baldwindavid]

@yara-blue - Just to make sure; did you read the PR description? I thought that was pretty well covered there, but maybe not. Or maybe there is a picker similar to netrw already in Zed that I have somehow missed these past couple years?

[yara-blue]

@dvdsk - Just to make sure; did you read the PR description? I thought that was pretty well covered there, but maybe not. Or maybe there is a picker similar to netrw already in Zed that I have somehow missed these past couple years?

To me it seems similar to file finder: toggle. Try running that in the command pallet.

[baldwindavid]

Yes, I am very familiar with the file finder and it is discussed in the PR description above. I must admit, I'm a little confused by this conversation's approach 😄 . Again, I'd just note that this is all covered in the PR description above and if you try this picker (or have used netrw or Helix's file explorer) you'll know they are quite different things. I'm happy to close and wait for the extension system if you'd prefer not spending time on looking at this feature at the moment as I know there are a lot of PRs to sift through.

[yara-blue]

I was short on time but did not want to leave you hanging, in hindsight that was wrong. My apologies.

If I understand correct this PR proposes a new picker which could be seen like a combination of the file finder and project picker. One question is should this be its own picker or an option on the existing file finder? Some pros to extending the file finder:

• enhanced discoverability (already known to users)
• shared functionality (like .gitignore)

Your PR description states a wider vision:

What's missing: A way to hierarchically browse files that's contextual (starts where you are), focused (one directory at a time), and centered (doesn't require looking to a sidebar).

As long time vim user I achieve contextuality with :cd. Maybe we could have something like that which would work for all pickers. Regarding focus, there could be an option to limit the depth of the finders traversal.

You mention netrw and how the project panel does not work as it is to the side. Why does is that a problem? Is there anything we can do to make that go away?

I see the work and effort you put in and truly it is great to see the community engage like this! This might however need some design work before we can ship code :(

[baldwindavid]

Thanks, @dvdsk - Trust me, I get it on the time crunch; I've been around this project for a long time and know there's a lot going on! There's no rush from my side. Anyway, don't sweat it.

On to the PR discussion:

could be seen like a combination of the file finder and project picker

I think that's a pretty fair assessment. What it ended up being is pretty much a Zed-ified version of the File Explorer added to Helix here... https://helix-editor.com/news/release-25-07-highlights/

The main difference is there are no live previews in Zed. I actually had live previews going when tabbing/arrowing through this file explorer, but tore it out prior to opening the PR because I knew introducing a new picker could be a stretch, let alone introducing live previews. Even so, yeah, it's roughly approximating similar to helix's file explorer, netrw, yazi, ranger; really any typical file explorer.

The key points being that it opens to a focused view of the directory of the file you're currently editing and that you can easily navigate to file in the same directory, up a level, and navigate directory-by-directory.

should this be its own picker or an option on the existing file finder

I'm not opposed to it being part of an existing picker; I just couldn't really make that work. The one I experimented the most with as mentioned in the description was the picker that opens via the workspace::Open command. That one at least is directory-centric, but was still kind of an awkward fit. I got that mostly working with a new command that would open it starting at the directory of the current file. Ultimately, that it allows for navigating to any directory, even above a worktree, made for some UX complications, especially in remotes, and I bailed.

Could something be added to the existing file finder? Maybe? As long as it displayed all the files in the current directory to explore and you move up and down directories. But then it seems like a pretty different thing. 🤷

You mention netrw and how the project panel does not work as it is to the side. Why is that a problem? Is there anything we can do to make that go away?

I've tried over the years to use persistent project panels (e.g. nerdtree). It is just not a pleasant experience for me. I guess I just tend to work in codebases where the files near the current one are often somewhat related so I jump around to siblings or those just above or below. An explorer that pops up and displays only the files in the current directory allows me to immediately find my place and effortlessly jump to files near the one it was opened from. This is opposed to a full project panel where I look to the left and then try to get my bearings amongst a mass of directories/files; that just breaks flow for me.

As for potential project panel changes, I think it would at least help if there were a command that would force close everything in the tree and open only the current directory with the current file highlighted. Probably that wouldn't be much of a lift that I could probably handle, but also I'd still be unlikely to use that panel anyway just because I can't 😆

All of this was mostly a solved problem for me in Zed via yazi integration. That works wonderfully...until you're remoting in to a container. Then you can open yazi in zed, but as soon as you select a file, there's no way to instruct Zed on the host to open the file in the current Zed window. As such, I've looked for ways to make this work well enough, but it's pretty much the project panel or the project panel :)

I'm not super worried about it now that I've got the feature working as I run my own build anyway. But, of course, if there's an opportunity to get it or something like it in core, and if it is useful to others, all the better.

[Dima-369]

Thank you for sharing!

I tested it and I noticed those 2 things:

Filtered text from search query is not highlighted

The file explorer from this PR:

It would be nice if the text would be highlighted like in file_finder::Toggle:

The modal goes off to bottom of screen on long file list

Might be my screen resolution, I am on 1280 x 800 MacBook resolution on macOS.

Here, I used arrow keys to select a file out of view, but I just can't see it.

[baldwindavid]

@Dima-369 Thanks for taking a look! The modal height has been changed to the default for the picker and matches should now be highlighted.

Also the "ignore" option has been completely removed. This tries to stick to a lot of the same precedent as set in modals like the file_picker, but I don't really think the ignore option is nearly as relevant when you're navigating directories as it is when you're searching across an entire project. If this is necessary it could be added in the future and likely alongside "Settings Support" mentioned in the added "Future Considerations" section of the PR description.

[cla-bot]

Thank you for your pull request and welcome to our community. We could not parse the GitHub identity of the following contributors: David Baldwin.
This is most likely caused by a git client misconfiguration; please make sure to:

1. check if your git client is configured with an email to sign commits git config --list | grep email
2. If not, set it up using git config --global user.email email@example.com
3. Make sure that the git commit email is configured in your GitHub account settings, see https://github.com/settings/emails

[baldwindavid]

Re: #44530 (comment) - Thanks, @maxbrunsfeld, I'll be happy to re-work this based upon #44530 if/when that one lands.

[P1n3appl3]

I'm not opposed to it being part of an existing picker; I just couldn't really make that work. The one I experimented the most with as mentioned in the description was the picker that opens via the workspace::Open command. That one at least is directory-centric, but was still kind of an awkward fit. I got that mostly working with a new command that would open it starting at the directory of the current file. Ultimately, that it allows for navigating to any directory, even above a worktree, made for some UX complications, especially in remotes, and I bailed.

After reading through this thread I'm pretty much convinced that we actually do want to go this route. The existing prompt_for_paths picker is able to provide the functionality you want with a couple changes that I think are totally tractable:

• Action to open it to the current directory rather than the worktree route
• Alternate select action to accept the currently matched subdir (effectively narrowing your search to that subdir) without literally opening the directory in zed.
• You can already navigate up a directory with ctrl-backspace to remove the previous path segment. If you think it's critical to the usability that there's a .. option at the top of the picker, that's also totally doable.

I think I'll close this for now and make an issue with the above feature requests. Let me know if there's additional functionality you think that picker would need, but unless it's really big stuff I don't think it's worth having a divergent implementation when the existing one is so close to the desired behavior.

[baldwindavid]

Thanks, @P1n3appl3, I'll push up where I got on that original workspace::Open variation. If we're considering going all in on leveraging that picker I'm pretty sure I can sidestep the issue I was running into. I won't particularly care whether my code is used or not, but should be a good example of what I'd like to see.