trouble.nvim

You can create a simple filter by providing a table where the keys correspond to item attributes. When using a table, all specified conditions are treated with logical AND (e.g., an item must match all attributes in the table to be kept).

-- Example: Keep diagnostics with severity error in the current buffer when its filetype is 'lua'
{
  modes = {
    my_diagnostics = {
      mode = 'diagnostics',
      filter = { buf = 0, ft = 'lua' },
    },
  },
}

For complex logic, you can provide a function as a filter. This function receives the list of items as a parameter and should return the filtered list of items.

-- Example: Keep items with severity HINT
{
  modes = {
    my_diagnostics = {
      mode = 'diagnostics',
      filter = function(items)
        return vim.tbl_filter(function(item)
          return item.severity == vim.diagnostic.severity.HINT
        end, items)
      end,
    },
  },
}

Before installing, ensure your environment meets these requirements:

• Neovim: >= 0.9.2
• Treesitter: Neovim >= 0.10.0 OR the markdown and markdown_inline treesitter parsers.
• LSP: A properly configured Neovim LSP client.
• Icons (Optional): nvim-web-devicons for file icons and a Nerd Font for severity and fold icons.
• Theme: A theme with properly configured highlight groups for Neovim Diagnostics.

The any filter provides logical disjunction (OR). An item is kept if it matches any of the conditions provided within the any table. This table can contain attribute tables, functions, or a mix of both.

-- Example: Keep diagnostics for the current buffer OR diagnostics with severity ERROR for the current project
{
  modes = {
    my_diagnostics = {
      mode = 'diagnostics',
      filter = {
        any = {
          buf = 0,
          {
            severity = vim.diagnostic.severity.ERROR,
            function(item)
              return item.filename:find((vim.loop or vim.uv).cwd(), 1, true)
            end,
          },
        },
      },
    },
  },
}

The not filter allows you to exclude items that match a specific criteria. Use the ['not'] key in your filter table to negate the results of the nested filter.

-- Example: Remove diagnostics with severity INFO
{
  modes = {
    my_diagnostics = {
      mode = 'diagnostics',
      filter = {
        ['not'] = { severity = vim.diagnostic.severity.INFO },
      },
    },
  },
}

The Trouble command is a wrapper around the Trouble API and supports the syntax: Trouble [mode] [action] [options]. You can use Lua code directly within the options.

Examples:

• Toggle diagnostics for the current buffer without focusing the Trouble window: Trouble diagnostics toggle focus=false filter.buf=0
• Show document symbols on the right, pinned to the buffer: Trouble symbols toggle pinned=true win.relative=win win.position=right
• Filter diagnostics by severity: Trouble diagnostics filter.severity=vim.diagnostic.severity.ERROR

Trouble.nvim is highly configurable via the opts table. Key configuration areas include:

• Window Behavior: focus (focus window on open), follow (follow cursor), pinned (bind window to current buffer), and auto_close/auto_open.
• Display: indent_guides (show tree indentation), multiline (render multi-line messages), and max_items (limit items per section).
• Preview: preview settings control the preview window type (e.g., main, split, float) and whether it uses a scratch buffer.
• Modes: Define custom views using modes. You can extend existing modes like lsp_base or create entirely new ones with custom filters and win options.
• Keys: Customize the interaction within the Trouble window. Default keys include q to close, ? for help, and various fold/navigation controls.

Create a custom mode that inherits from diagnostics but applies a filter to only show items where buf = 0 (the current buffer).

{
  modes = {
    diagnostics_buffer = {
      mode = "diagnostics", -- inherit from diagnostics mode
      filter = { buf = 0 }, -- filter diagnostics to the current buffer
    },
  }
}

Create a mode that shows diagnostics from the current buffer OR errors found within the current project directory. This uses an any filter containing the current buffer ID and a function that checks if the item's filename starts with the current working directory.

{
  modes = {
    mydiags = {
      mode = "diagnostics", -- inherit from diagnostics mode
      filter = {
        any = {
          buf = 0, -- current buffer
          {
            severity = vim.diagnostic.severity.ERROR, -- errors only
            -- limit to files in the current project
            function(item)
              return item.filename:find((vim.loop or vim.uv).cwd(), 1, true)
            end,
          },
        },
      },
    }
  }
}

You can configure a specific mode (e.g., preview_float) to display diagnostic previews in a floating window. Use the preview table within a mode to define type = "float" and specify its relative position, border, title, position (offset), and size.

{
  modes = {
    preview_float = {
      mode = "diagnostics",
      preview = {
        type = "float",
        relative = "editor",
        border = "rounded",
        title = "Preview",
        title_pos = "center",
        position = { 0, -2 },
        size = { width = 0.3, height = 0.3 },
        zindex = 200,
      },
    },
  },
}

To show diagnostic previews in a split window next to the Trouble list, set the preview.type to "split". You can define the relative position (e.g., "win") and the position (e.g., "right") along with a size.

{
  modes = {
    test = {
      mode = "diagnostics",
      preview = {
        type = "split",
        relative = "win",
        position = "right",
        size = 0.3,
      },
    },
  },
}