snacks-file-browser.nvim

A modern file browser for Neovim built on top of snacks.nvim that provides telescope-style navigation in a floating picker interface.

Features

• 🚀 Fast and lightweight - Built on snacks.nvim picker
• 📁 Telescope-style navigation - Use <C-l> and <C-h> for intuitive browsing
• 🎨 Proper file icons - Integrates with your icon theme (mini.icons, nvim-web-devicons)
• ⚡ Non-recursive browsing - Shows only current directory contents
• 🔧 Highly configurable - Customize keymaps, icons, and behavior
• 🌟 Modern Lua plugin - Type-annotated with lazy loading

Requirements

• Neovim >= 0.9.0
• snacks.nvim

Installation

With lazy.nvim

{
    "your-username/snacks-file-browser.nvim",
    dependencies = { "folke/snacks.nvim" },
    opts = {
        -- Configuration options (see below)
    },
    keys = {
        { "<leader>e", function() require("snacks-file-browser").browse_current() end, desc = "File Browser" },
        { "<leader>E", function() require("snacks-file-browser").browse_cwd() end, desc = "File Browser (CWD)" },
    },
}

With other plugin managers

-- Add the plugin
require("snacks-file-browser").setup({
    -- Your configuration
})

-- Set up keymaps
vim.keymap.set("n", "<leader>e", function() require("snacks-file-browser").browse_current() end, { desc = "File Browser" })
vim.keymap.set("n", "<leader>E", function() require("snacks-file-browser").browse_cwd() end, { desc = "File Browser (CWD)" })

Usage

Basic Commands

• Browse current file's directory: require("snacks-file-browser").browse_current()
• Browse current working directory: require("snacks-file-browser").browse_cwd()
• Browse specific directory: require("snacks-file-browser").browse("/path/to/directory")

Navigation

Once the file browser is open:

• <C-l> - Enter directories or open files
• <C-h> - Go back to parent directory
• <CR> - Alternative to <C-l> (enter/open)
• Type to filter - Start typing to filter files and directories
• <Esc> - Close the browser

Configuration

Default configuration:

{
    keymaps = {
        enter = "<C-l>",        -- Key to enter directories or open files
        back = "<C-h>",         -- Key to go back to parent directory
        confirm = "<CR>",       -- Alternative key to enter/open
    },
    icons = {
        enabled = true,         -- Whether to show file icons
        dir = "📁 ",           -- Icon for directories
        file = "📄 ",          -- Default icon for files
    },
    show_hidden = false,        -- Whether to show hidden files (starting with .)
    sort_directories_first = true, -- Whether directories appear before files
}

Example Configurations

Telescope-style keymaps

{
    keymaps = {
        enter = "<C-l>",
        back = "<C-h>",
        confirm = "<CR>",
    },
}

Different navigation keys

{
    keymaps = {
        enter = "<Tab>",
        back = "<S-Tab>",
        confirm = "<CR>",
    },
}

Show hidden files

{
    show_hidden = true,
}

Custom icons

{
    icons = {
        enabled = true,
        dir = "󰉋 ",
        file = "󰈔 ",
    },
}

API

Setup

require("snacks-file-browser").setup(opts)

Functions

browse(start_dir?)

Open file browser in specified directory.

• start_dir (string, optional): Directory to start browsing from

browse_current()

Browse current file's directory.

browse_cwd()

Browse current working directory.

Comparison with Other File Browsers

Feature	snacks-file-browser	telescope file_browser	nvim-tree	oil.nvim
Interface	Floating picker	Floating picker	Sidebar tree	Buffer
Navigation	Telescope-style	Telescope-style	Tree expansion	Buffer editing
Performance	Fast	Fast	Medium	Fast
Dependencies	snacks.nvim	telescope.nvim	None	None
File operations	View/Open only	Full CRUD	Full CRUD	Full CRUD

Why snacks-file-browser?

• Lightweight: Built on the fast snacks.nvim picker infrastructure
• Familiar: Uses telescope-style navigation that many users already know
• Consistent: Integrates seamlessly with other snacks.nvim components
• Simple: Focused on file browsing without complex file operations
• Modern: Pure Lua with type annotations and lazy loading

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.