Trouble: A Configurable Tree View for Diagnostics, References, and LSP Results

If you've ever found yourself squinting at Neovim's built-in diagnostic window, or bouncing between multiple quickfix lists to track errors, references, and LSP output, you’ve probably wished for something more organized. Enter Trouble — a Neovim plugin by folke that gives you a fully configurable tree view for diagnostics, references, and LSP results. It’s like a Swiss Army knife for navigating code issues, but without the clutter.

What It Does

Trouble takes all the scattered information you get from Neovim’s built-in tools and LSP servers and consolidates it into a clean, tree-based panel. You can view:

• Diagnostics (errors, warnings, hints) from the current buffer or the entire workspace.
• LSP references, definitions, and implementations.
• Quickfix and location list items.
• Custom lists from any source (vim.diagnostic, LSP handlers, or your own data).

The tree view is fully keyboard-driven, so you can jump between items, expand/collapse nodes, and even apply filters without lifting your hands off the home row. It’s not just a pretty UI — it’s built to be fast and flexible.

Why It’s Cool

What makes Trouble stand out is how configurable it is. You can define custom "modes" that dictate which data sources to use, how to group results, and what to display. For example:

• A “workspace diagnostics” mode that shows all errors across your project.
• A “references” mode that groups results by file or symbol.
• A “quickfix” mode that works like a smarter, filterable quickfix list.

It also integrates tightly with Neovim’s built-in LSP client, so you get things like hover previews, goto-definition from within the tree, and automatic updates when you save files. The UI itself is minimal and unobtrusive — it can be toggled on/off with a single keybinding, and it respects your color scheme.

One neat trick: you can use Trouble as a replacement for the default vim.diagnostic.open_float() by configuring it to show a floating window instead of a full sidebar. That’s the kind of flexibility that makes it feel like it was designed for your workflow, not the other way around.

How to Try It

If you’re using a plugin manager like lazy.nvim, adding Trouble is straightforward:

{
  "folke/trouble.nvim",
  opts = {}, -- for default setup
  cmd = "Trouble",
  keys = {
    { "<leader>xx", "<cmd>Trouble diagnostics toggle<cr>", desc = "Diagnostics (Trouble)" },
    { "<leader>xX", "<cmd>Trouble diagnostics toggle filter.buf=0<cr>", desc = "Buffer Diagnostics (Trouble)" },
    { "<leader>cs", "<cmd>Trouble symbols toggle<cr>", desc = "Symbols (Trouble)" },
    { "<leader>cl", "<cmd>Trouble lsp toggle<cr>", desc = "LSP References / Definitions (Trouble)" },
    { "<leader>xL", "<cmd>Trouble loclist toggle<cr>", desc = "Location List (Trouble)" },
    { "<leader>xQ", "<cmd>Trouble qflist toggle<cr>", desc = "Quickfix List (Trouble)" },
  },
}

That’s the basic setup. You can then use:

• :Trouble diagnostics to show all diagnostics.
• :Trouble lsp_references to show references for the symbol under the cursor.
• :Trouble symbols to show document symbols.

Check the README for more advanced configuration — there’s a lot to tweak if you want to.

Final Thoughts

Trouble is one of those plugins that feels obvious in hindsight. Instead of wrestling with Neovim’s built-in UI quirks, you get a single, consistent panel for everything diagnostics and LSP-related. It’s not flashy, but it’s remarkably practical. If you spend a lot of time cleaning up errors or navigating code in Neovim, give it a shot — you might wonder how you lived without it.

Follow @githubprojects for more developer tools and Neovim plugins.