From 6500760f45a617e08d0ad10b3bb7d5f9997b0944 Mon Sep 17 00:00:00 2001
From: runie <5571284+Run1e@users.noreply.github.com>
Date: Mon, 11 May 2026 00:33:47 +0200
Subject: [PATCH 1/2] feat: add option that pauses autoscrolling while browsing
 term buf

---
 lua/toggleterm/config.lua   |  1 +
 lua/toggleterm/terminal.lua | 12 +++++++++++-
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/lua/toggleterm/config.lua b/lua/toggleterm/config.lua
index 736d8cf8..5c8473f7 100644
--- a/lua/toggleterm/config.lua
+++ b/lua/toggleterm/config.lua
@@ -61,6 +61,7 @@ local config = {
   shell = vim.o.shell,
   autochdir = false,
   auto_scroll = true,
+  conditional_auto_scroll = false,
   winbar = {
     enabled = false,
     name_formatter = function(term) return fmt("%d:%s", term.id, term:_display_name()) end,
diff --git a/lua/toggleterm/terminal.lua b/lua/toggleterm/terminal.lua
index 19231c40..6689d596 100644
--- a/lua/toggleterm/terminal.lua
+++ b/lua/toggleterm/terminal.lua
@@ -88,6 +88,7 @@ local terminals = {}
 --- @field hidden boolean whether or not to include this terminal in the terminals list
 --- @field close_on_exit boolean? whether or not to close the terminal window when the process exits
 --- @field auto_scroll boolean? whether or not to scroll down on terminal output
+--- @field conditional_auto_scroll boolean? whether to pause autoscrolling while navigating terminal buffer
 --- @field float_opts table<string, any>?
 --- @field display_name string?
 --- @field env table<string, string> environmental variables passed to jobstart()
@@ -210,6 +211,8 @@ function Terminal:new(term)
   term.float_opts = vim.tbl_deep_extend("keep", term.float_opts or {}, conf.float_opts)
   term.clear_env = vim.F.if_nil(term.clear_env, conf.clear_env)
   term.auto_scroll = vim.F.if_nil(term.auto_scroll, conf.auto_scroll)
+  term.conditional_auto_scroll =
+    vim.F.if_nil(term.conditional_auto_scroll, conf.conditional_auto_scroll)
   term.env = vim.F.if_nil(term.env, conf.env)
   term.hidden = vim.F.if_nil(term.hidden, false)
   term.on_create = vim.F.if_nil(term.on_create, conf.on_create)
@@ -380,7 +383,14 @@ end
 function Terminal:__make_output_handler(handler)
   if self.auto_scroll or handler then
     return function(...)
-      if self.auto_scroll then self:scroll_bottom() end
+      if self.auto_scroll then
+        if self.conditional_auto_scroll then
+          local cursor = vim.api.nvim_win_get_cursor(self.window)
+          if cursor[1] == vim.api.nvim_buf_line_count(self.bufnr) then self:scroll_bottom() end
+        else
+          self:scroll_bottom()
+        end
+      end
       if handler then handler(self, ...) end
     end
   end

From 91564fbfd2eaf4f5f6f943fcb7edeb3e0df1aa5f Mon Sep 17 00:00:00 2001
From: runie <5571284+Run1e@users.noreply.github.com>
Date: Fri, 15 May 2026 06:43:43 +0200
Subject: [PATCH 2/2] fix: move conditional_auto_scroll loginc into
 Terminal::scroll_bottom after window checks

---
 lua/toggleterm/terminal.lua | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/lua/toggleterm/terminal.lua b/lua/toggleterm/terminal.lua
index 6689d596..c28e9079 100644
--- a/lua/toggleterm/terminal.lua
+++ b/lua/toggleterm/terminal.lua
@@ -313,7 +313,13 @@ end
 
 function Terminal:scroll_bottom()
   if not api.nvim_buf_is_loaded(self.bufnr) or not api.nvim_buf_is_valid(self.bufnr) then return end
-  if ui.term_has_open_win(self) then api.nvim_buf_call(self.bufnr, ui.scroll_to_bottom) end
+  if ui.term_has_open_win(self) then
+    if self.conditional_auto_scroll then
+      local cursor = vim.api.nvim_win_get_cursor(self.window)
+      if cursor[1] < vim.api.nvim_buf_line_count(self.bufnr) then return end
+    end
+    api.nvim_buf_call(self.bufnr, ui.scroll_to_bottom)
+  end
 end
 
 function Terminal:is_focused() return self.window == api.nvim_get_current_win() end
@@ -383,14 +389,7 @@ end
 function Terminal:__make_output_handler(handler)
   if self.auto_scroll or handler then
     return function(...)
-      if self.auto_scroll then
-        if self.conditional_auto_scroll then
-          local cursor = vim.api.nvim_win_get_cursor(self.window)
-          if cursor[1] == vim.api.nvim_buf_line_count(self.bufnr) then self:scroll_bottom() end
-        else
-          self:scroll_bottom()
-        end
-      end
+      if self.auto_scroll then self:scroll_bottom() end
       if handler then handler(self, ...) end
     end
   end