A File Explorer For Neovim Written In Lua

Automatic updates

File type icons

Git integration

Diagnostics integration: LSP and COC

(Live) filtering

Cut, copy, paste, rename, delete, create

Highly customisable

Take a look at the wiki for Showcases, Tips, Recipes and more.

Questions and general support: Discussions

• Requirements
• Installing
• Quick Start
  • Setup
  • Help
  • Custom Mappings
  • Highlight Groups
• Commands
• Roadmap
• API
• Contributing
• Screenshots
• Team

Requirements

Nvim >= 0.10. At least n - 0.1 stable Nvim compatibility is guaranteed. You may use a compat-nvim-0.X tag for earlier Nvim versions, however they will receive no updates or support.

nvim-web-devicons is optional and used to display file icons. It requires a patched font. Your terminal emulator must be configured to use that font, usually "Hack Nerd Font"

Installing

Please install via your preferred package manager. See Installation for some specific package manager instructions.

Major or minor versions may be specified via tags: v<MAJOR> e.g. v1 or v<MAJOR>.<MINOR> e.g. v1.23

Quick Start

Install the plugins via your package manager: "nvim-tree/nvim-tree.lua" "nvim-tree/nvim-web-devicons"

Disabling netrw is strongly advised, see :help nvim-tree-netrw

Setup

Setup the plugin in your init.lua.

See :help nvim-tree-setup and :help nvim-tree-config-default

  -- disable netrw at the very start of your init.lua
  vim.g.loaded_netrw = 1
  vim.g.loaded_netrwPlugin = 1

  -- optionally enable 24-bit colour
  vim.opt.termguicolors = true

  -- empty setup using defaults
  require("nvim-tree").setup()

  -- OR setup with a config

  ---@type nvim_tree.config
  local config = {
    sort = {
      sorter = "case_sensitive",
    },
    view = {
      width = 30,
    },
    renderer = {
      group_empty = true,
    },
    filters = {
      dotfiles = true,
    },
  }
  require("nvim-tree").setup(config)

Help

Open the tree: :NvimTreeOpen

Show the mappings: g?

Custom Mappings

:help nvim-tree-mappings-default are applied by default however you may customise via :help nvim_tree.config {on_attach} e.g.

  local function my_on_attach(bufnr)
    local api = require "nvim-tree.api"

    local function opts(desc)
      return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
    end

    -- default mappings
    api.map.on_attach.default(bufnr)

    -- custom mappings
    vim.keymap.set("n", "<C-t>", api.tree.change_root_to_parent,        opts("Up"))
    vim.keymap.set("n", "?",     api.tree.toggle_help,                  opts("Help"))
  end

  -- pass to setup along with your other config
  require("nvim-tree").setup({
    ---
    on_attach = my_on_attach,
    ---
  })

Highlight Groups

See :help nvim-tree-highlight-groups

Run :NvimTreeHiTest to show all the highlights that nvim-tree uses.

They can be customised before or after setup is called and will be immediately applied at runtime. e.g.

  vim.cmd([[
      :hi      NvimTreeExecFile    guifg=#ffa0a0
      :hi      NvimTreeSpecialFile guifg=#ff80ff gui=underline
      :hi      NvimTreeSymlink     guifg=Yellow  gui=italic
      :hi link NvimTreeImageFile   Title
  ]])

Commands

See :help nvim-tree-commands

Some commands may be executed with a bang ! or take a path string argument.

All commands execute public API.

Some basic commands:

:NvimTreeFocus :help nvim_tree.api.tree.open()

  require("nvim-tree.api").tree.open()

:NvimTreeToggle :help nvim_tree.api.tree.toggle()

  require("nvim-tree.api").tree.toggle({
    path = "<args>",
    find_file = false,
    update_root = false,
    focus = true,
  })

:NvimTreeFindFile :help nvim_tree.api.tree.find_file()

  require("nvim-tree.api").tree.find_file({
    open = true,
    update_root = "<bang>",
    focus = true,
  })

:NvimTreeCollapse :help nvim_tree.api.tree.collapse_all()

  require("nvim-tree.api").tree.collapse_all({
    keep_buffers = false
  })

Roadmap

nvim-tree is stable and new major features will not be added. The focus is on existing user experience.

Users are encouraged to add their own custom features via the public API.

Development is focused on:

• Bug fixes
• Performance
• Quality of Life improvements
• API / Events
• Enhancements to existing features
• Multi-instance capabilities

API

nvim-tree exposes a public API. This is non breaking, with additions made as necessary. See :help nvim-tree-api

See wiki Recipes and Tips for ideas and inspiration.

Please raise a feature request if the API is insufficient for your needs. Contributions are always welcome, see below.

You may also subscribe to events that nvim-tree will dispatch in a variety of situations, see :help nvim-tree-events

Contributing

PRs are always welcome. See CONTRIBUTING and wiki: Development to get started.

See bug and PR Please issues if you are looking for some work to get you started.

Screenshots

See Showcases wiki page for examples of user's configurations with sources.

Please add your own!

Team

• @alex-courtis Arch Linux
• @gegoune macOS
• @Akmadan23 Linux
• @dependabot[bot] Ubuntu Linux