diff --git a/plugins/by-name/trouble/default.nix b/plugins/by-name/trouble/default.nix
index 1d81f507..a35306ec 100644
--- a/plugins/by-name/trouble/default.nix
+++ b/plugins/by-name/trouble/default.nix
@@ -115,186 +115,267 @@ lib.nixvim.neovim-plugin.mkNeovimPlugin {
   ];
 
   settingsOptions = {
-    position =
-      defaultNullOpts.mkEnum
-        [
-          "top"
-          "left"
-          "right"
-          "bottom"
-        ]
-        "bottom"
-        ''
-          Position of the list.
-        '';
-
-    height = defaultNullOpts.mkInt 10 ''
-      Height of the trouble list when position is top or bottom.
-    '';
-
-    width = defaultNullOpts.mkInt 50 ''
-      Width of the list when position is left or right.
-    '';
-
-    icons = defaultNullOpts.mkBool true "Use devicons for filenames";
-
-    mode = defaultNullOpts.mkEnum [
-      "workspace_diagnostics"
-      "document_diagnostics"
-      "quickfix"
-      "lsp_references"
-      "loclist"
-    ] "workspace_diagnostics" "Mode for default list";
-
-    fold_open = defaultNullOpts.mkStr "" "Icon used for open folds";
-
-    fold_closed = defaultNullOpts.mkStr "" "Icon used for closed folds";
-
-    group = defaultNullOpts.mkBool true "Group results by file";
-
-    padding = defaultNullOpts.mkBool true "Add an extra new line on top of the list";
-
-    cycle_results = defaultNullOpts.mkBool true "Whether to cycle item list when reaching beginning or end of list";
-
-    action_keys =
-      lib.mapAttrs
-        (
-          action: config:
-          defaultNullOpts.mkNullable (
-            with lib.types; either str (listOf str)
-          ) config.default config.description
-        )
-        {
-          close = {
-            default = "q";
-            description = "Close the list";
-          };
-          cancel = {
-            default = "<esc>";
-            description = "Cancel the preview and get back to your last window / buffer / cursor";
-          };
-          refresh = {
-            default = "r";
-            description = "Manually refresh";
-          };
-          jump = {
-            default = [
-              "<cr>"
-              "<tab>"
-            ];
-            description = "Jump to the diagnostic or open / close folds";
-          };
-          open_split = {
-            default = [ "<c-x>" ];
-            description = "Open buffer in new split";
-          };
-          open_vsplit = {
-            default = [ "<c-v>" ];
-            description = "Open buffer in new vsplit";
-          };
-          open_tab = {
-            default = [ "<c-t>" ];
-            description = "Open buffer in new tab";
-          };
-          jump_close = {
-            default = [ "o" ];
-            description = "Jump to the diagnostic and close the list";
-          };
-          toggle_mode = {
-            default = "m";
-            description = "toggle between 'workspace' and 'document' diagnostics mode";
-          };
-          toggle_preview = {
-            default = "P";
-            description = "Toggle auto_preview";
-          };
-          hover = {
-            default = "K";
-            description = "Opens a small popup with the full multiline message";
-          };
-          preview = {
-            default = "p";
-            description = "Preview the diagnostic location";
-          };
-          close_folds = {
-            default = [
-              "zM"
-              "zm"
-            ];
-            description = "Close all folds";
-          };
-          open_folds = {
-            default = [
-              "zR"
-              "zr"
-            ];
-            description = "Open all folds";
-          };
-          toggle_fold = {
-            default = [
-              "zA"
-              "za"
-            ];
-            description = "Toggle fold of current file";
-          };
-          previous = {
-            default = "k";
-            description = "Previous item";
-          };
-          next = {
-            default = "j";
-            description = "Next item";
-          };
-        };
-
-    indent_lines = defaultNullOpts.mkBool true ''
-      Add an indent guide below the fold icons.
-    '';
-
-    win_config = defaultNullOpts.mkAttrsOf lib.types.anything {
-      border = "single";
-    } "Configuration for floating windows. See `|nvim_open_win()|`.";
-
     auto_close = defaultNullOpts.mkBool false ''
       Automatically close the list when you have no diagnostics.
     '';
 
     auto_preview = defaultNullOpts.mkBool true ''
       Automatically preview the location of the diagnostic.
-      <esc> to close preview and go back to last window.
+      `<esc>` to close preview and go back to last window.
     '';
 
-    auto_fold = defaultNullOpts.mkBool false ''
-      Automatically fold a file trouble list at creation.
+    auto_refresh = defaultNullOpts.mkBool false ''
+      Automatically refresh when open.
     '';
 
-    auto_jump = defaultNullOpts.mkListOf lib.types.str [ "lsp_definitions" ] ''
-      For the given modes, automatically jump if there is only a single result.
+    auto_jump = defaultNullOpts.mkBool false ''
+      Auto jump to the item when there's only one.
     '';
 
-    include_declaration = defaultNullOpts.mkListOf lib.types.str [
-      "lsp_references"
-      "lsp_implementations"
-      "lsp_definitions"
-    ] "For the given modes, include the declaration of the current symbol in the results.";
+    focus = defaultNullOpts.mkBool false ''
+      Focus the window when opened.
+    '';
 
-    signs =
-      lib.mapAttrs
-        (diagnostic: default: defaultNullOpts.mkStr default "Icon/text for ${diagnostic} diagnostics.")
+    restore = defaultNullOpts.mkBool true ''
+      Restores the last location in the list when opening.
+    '';
+
+    follow = defaultNullOpts.mkBool true ''
+      Follow the current item.
+    '';
+
+    indent_guides = defaultNullOpts.mkBool true ''
+      Add indent guides.
+    '';
+
+    max_items = defaultNullOpts.mkUnsignedInt 200 ''
+      Limit the number of items that can be displayed per section.
+    '';
+
+    multiline = defaultNullOpts.mkBool true ''
+      Render multi-line messages.
+    '';
+
+    pinned = defaultNullOpts.mkBool false ''
+      Whether the opened trouble window will be bound to the current buffer.
+    '';
+
+    warn_no_results = defaultNullOpts.mkBool true ''
+      Show a warning when there are no results.
+    '';
+
+    open_no_results = defaultNullOpts.mkBool false ''
+      Open the trouble window when there are no results.
+    '';
+
+    win = defaultNullOpts.mkAttrsOf lib.types.anything { } ''
+      Window options for the results window. Can be a split or a floating window.
+
+      See `|nvim_open_win()|`.
+    '';
+
+    preview =
+      defaultNullOpts.mkAttrsOf lib.types.anything
         {
-          error = "";
-          warning = "";
-          hint = "";
-          information = "";
-          other = "﫠";
-        };
+          type = "main";
+          scratch = true;
+        }
+        ''
+          Window options for the preview window.
 
-    use_diagnostic_signs = defaultNullOpts.mkBool false ''
-      Enabling this will use the signs defined in your lsp client
-    '';
+          See `|nvim_open_win()|`.
+        '';
+
+    keys =
+      defaultNullOpts.mkAttrsOf lib.types.anything
+        {
+          "?" = "help";
+          r = "refresh";
+          R = "toggle_refresh";
+          q = "close";
+          o = "jump_close";
+          "<esc>" = "cancel";
+          "<cr>" = "jump";
+          "<2-leftmouse>" = "jump";
+          "<c-s>" = "jump_split";
+          "<c-v>" = "jump_vsplit";
+          "}" = "next";
+          "]]" = "next";
+          "{" = "prev";
+          "[[" = "prev";
+          dd = "delete";
+          d = {
+            action = "delete";
+            mode = "v";
+          };
+          i = "inspect";
+          p = "preview";
+          P = "toggle_preview";
+          zo = "fold_open";
+          zO = "fold_open_recursive";
+          zc = "fold_close";
+          zC = "fold_close_recursive";
+          za = "fold_toggle";
+          zA = "fold_toggle_recursive";
+          zm = "fold_more";
+          zM = "fold_close_all";
+          zr = "fold_reduce";
+          zR = "fold_open_all";
+          zx = "fold_update";
+          zX = "fold_update_all";
+          zn = "fold_disable";
+          zN = "fold_enable";
+          zi = "fold_toggle_enable";
+          gb = {
+            action.__raw = ''
+              function(view)
+                view:filter({ buf = 0 }, { toggle = true })
+              end
+            '';
+            desc = "Toggle Current Buffer Filter";
+          };
+          s = {
+            action.__raw = ''
+              function(view)
+                 local f = view:get_filter("severity")
+                 local severity = ((f and f.filter.severity or 0) + 1) % 5
+                 view:filter({ severity = severity }, {
+                   id = "severity",
+                   template = "{hl:Title}Filter:{hl} {severity}",
+                   del = severity == 0,
+                 })
+              end
+            '';
+            desc = "Toggle Severity Filter";
+          };
+        }
+        ''
+          Key mappings can be set to the name of a builtin action,
+          or you can define your own custom action.
+        '';
+
+    modes =
+      defaultNullOpts.mkAttrsOf lib.types.anything
+        {
+          lsp_references = {
+            params = {
+              include_declaration = true;
+            };
+          };
+          lsp_base = {
+            params = {
+              include_current = false;
+            };
+          };
+          symbols = {
+            desc = "document symbols";
+            mode = "lsp_document_symbols";
+            focus = false;
+            win = {
+              position = "right";
+            };
+            filter = {
+              "not" = {
+                ft = "lua";
+                kind = "Package";
+              };
+              any = {
+                ft = [
+                  "help"
+                  "markdown"
+                ];
+                kind = [
+                  "Class"
+                  "Constructor"
+                  "Enum"
+                  "Field"
+                  "Function"
+                  "Interface"
+                  "Method"
+                  "Module"
+                  "Namespace"
+                  "Package"
+                  "Property"
+                  "Struct"
+                  "Trait"
+                ];
+              };
+            };
+          };
+        }
+        ''
+          Customize the various builtin modes or define your own.
+        '';
+
+    icons = defaultNullOpts.mkAttrsOf lib.types.anything {
+      indent = {
+        top = "│ ";
+        middle = "├╴";
+        last = "└╴";
+        fold_open = " ";
+        fold_closed = " ";
+        ws = "  ";
+      };
+      folder_closed = " ";
+      folder_open = " ";
+      kinds = {
+        Array = " ";
+        Boolean = "󰨙 ";
+        Class = " ";
+        Constant = "󰏿 ";
+        Constructor = " ";
+        Enum = " ";
+        EnumMember = " ";
+        Event = " ";
+        Field = " ";
+        File = " ";
+        Function = "󰊕 ";
+        Interface = " ";
+        Key = " ";
+        Method = "󰊕 ";
+        Module = " ";
+        Namespace = "󰦮 ";
+        Null = " ";
+        Number = "󰎠 ";
+        Object = " ";
+        Operator = " ";
+        Package = " ";
+        Property = " ";
+        String = " ";
+        Struct = "󰆼 ";
+        TypeParameter = " ";
+        Variable = "󰀫 ";
+      };
+    } "Define custom icons.";
   };
 
   extraConfig = cfg: {
+    # TODO: introduced 2024-10-12: remove after 24.11
+    warnings =
+      let
+        definedOpts = lib.filter (opt: lib.hasAttrByPath (lib.toList opt) cfg.settings) [
+          "action_keys"
+          "position"
+          "height"
+          "width"
+          "mode"
+          "fold_open"
+          "fold_close"
+          "group"
+          "padding"
+          "cycle_results"
+          "indent_lines"
+          "win_config"
+          "include_declaration"
+          "signs"
+          "use_diagnostic_signs"
+        ];
+      in
+      lib.optional (definedOpts != [ ]) ''
+        Nixvim(plugins.trouble): The following v2 settings options are no longer supported in v3:
+        ${lib.concatMapStringsSep "\n" (opt: "  - ${lib.showOption (lib.toList opt)}") definedOpts}
+      '';
+
     # TODO: added 2024-09-20 remove after 24.11
     plugins.web-devicons = lib.mkIf (
       !(
diff --git a/tests/test-sources/plugins/by-name/trouble/default.nix b/tests/test-sources/plugins/by-name/trouble/default.nix
index 93900939..9ca09838 100644
--- a/tests/test-sources/plugins/by-name/trouble/default.nix
+++ b/tests/test-sources/plugins/by-name/trouble/default.nix
@@ -20,63 +20,184 @@
       enable = true;
 
       settings = {
-        position = "bottom";
-        height = 10;
-        width = 50;
-        icons = true;
-        mode = "workspace_diagnostics";
-        fold_open = "";
-        fold_closed = "";
-        group = true;
-        padding = true;
-        action_keys = {
-          close = "q";
-          cancel = "<esc>";
-          refresh = "r";
-          jump = [
-            "<cr>"
-            "<tab>"
-          ];
-          open_split = [ "<c-x>" ];
-          open_vsplit = [ "<c-v>" ];
-          open_tab = [ "<c-t>" ];
-          jump_close = [ "o" ];
-          toggle_mode = "m";
-          toggle_preview = "P";
-          hover = "K";
-          preview = "p";
-          close_folds = [
-            "zM"
-            "zm"
-          ];
-          open_folds = [
-            "zR"
-            "zr"
-          ];
-          toggle_fold = [
-            "zA"
-            "za"
-          ];
-          previous = "k";
-          next = "j";
-        };
-        indent_lines = true;
-        win_config = {
-          border = "single";
-        };
-        auto_open = false;
+        debug = false;
         auto_close = false;
+        auto_open = false;
         auto_preview = true;
-        auto_fold = false;
-        auto_jump = [ "lsp_definitions" ];
-        signs = {
-          error = "";
-          warning = "";
-          hint = "";
-          information = "";
-          other = "﫠";
+        auto_refresh = true;
+        auto_jump = false;
+        focus = false;
+        restore = true;
+        follow = true;
+        indent_guides = true;
+        max_items = 200;
+        multiline = true;
+        pinned = false;
+        warn_no_results = true;
+        open_no_results = false;
+        win = { };
+        preview = {
+          type = "main";
+          scratch = true;
+        };
+        throttle = {
+          refresh = 20;
+          update = 10;
+          render = 10;
+          follow = 100;
+          preview = {
+            ms = 100;
+            debounce = true;
+          };
+        };
+        keys = {
+          "?" = "help";
+          r = "refresh";
+          R = "toggle_refresh";
+          q = "close";
+          o = "jump_close";
+          "<esc>" = "cancel";
+          "<cr>" = "jump";
+          "<2-leftmouse>" = "jump";
+          "<c-s>" = "jump_split";
+          "<c-v>" = "jump_vsplit";
+          "}" = "next";
+          "]]" = "next";
+          "{" = "prev";
+          "[[" = "prev";
+          dd = "delete";
+          d = {
+            action = "delete";
+            mode = "v";
+          };
+          i = "inspect";
+          p = "preview";
+          P = "toggle_preview";
+          zo = "fold_open";
+          zO = "fold_open_recursive";
+          zc = "fold_close";
+          zC = "fold_close_recursive";
+          za = "fold_toggle";
+          zA = "fold_toggle_recursive";
+          zm = "fold_more";
+          zM = "fold_close_all";
+          zr = "fold_reduce";
+          zR = "fold_open_all";
+          zx = "fold_update";
+          zX = "fold_update_all";
+          zn = "fold_disable";
+          zN = "fold_enable";
+          zi = "fold_toggle_enable";
+          gb = {
+            action.__raw = ''
+              function(view)
+                view:filter({ buf = 0 }, { toggle = true })
+              end
+            '';
+            desc = "Toggle Current Buffer Filter";
+          };
+          s = {
+            action.__raw = ''
+              function(view)
+                 local f = view:get_filter("severity")
+                 local severity = ((f and f.filter.severity or 0) + 1) % 5
+                 view:filter({ severity = severity }, {
+                   id = "severity",
+                   template = "{hl:Title}Filter:{hl} {severity}",
+                   del = severity == 0,
+                 })
+              end
+            '';
+            desc = "Toggle Severity Filter";
+          };
+        };
+        modes = {
+          lsp_references = {
+            params = {
+              include_declaration = true;
+            };
+          };
+          lsp_base = {
+            params = {
+              include_current = false;
+            };
+          };
+          symbols = {
+            desc = "document symbols";
+            mode = "lsp_document_symbols";
+            focus = false;
+            win = {
+              position = "right";
+            };
+            filter = {
+              "not" = {
+                ft = "lua";
+                kind = "Package";
+              };
+              any = {
+                ft = [
+                  "help"
+                  "markdown"
+                ];
+                kind = [
+                  "Class"
+                  "Constructor"
+                  "Enum"
+                  "Field"
+                  "Function"
+                  "Interface"
+                  "Method"
+                  "Module"
+                  "Namespace"
+                  "Package"
+                  "Property"
+                  "Struct"
+                  "Trait"
+                ];
+              };
+            };
+          };
+        };
+        icons = {
+          indent = {
+            top = "│ ";
+            middle = "├╴";
+            last = "└╴";
+            fold_open = " ";
+            fold_closed = " ";
+            ws = "  ";
+          };
+          folder_closed = " ";
+          folder_open = " ";
+          kinds = {
+            Array = " ";
+            Boolean = "󰨙 ";
+            Class = " ";
+            Constant = "󰏿 ";
+            Constructor = " ";
+            Enum = " ";
+            EnumMember = " ";
+            Event = " ";
+            Field = " ";
+            File = " ";
+            Function = "󰊕 ";
+            Interface = " ";
+            Key = " ";
+            Method = "󰊕 ";
+            Module = " ";
+            Namespace = "󰦮 ";
+            Null = " ";
+            Number = "󰎠 ";
+            Object = " ";
+            Operator = " ";
+            Package = " ";
+            Property = " ";
+            String = " ";
+            Struct = "󰆼 ";
+            TypeParameter = " ";
+            Variable = "󰀫 ";
+          };
         };
-        use_diagnostic_signs = false;
       };
     };
   };