Skip to main content

​
Overview

Scrolling actions allow you to navigate through terminal output and scrollback history. WezTerm provides fine-grained control over scrolling, including page-based scrolling, line-by-line navigation, and semantic navigation by shell prompts.

​
Basic Scrolling

​
ScrollByPage

Scroll by full or partial pages: 
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {
  -- Scroll up one page
  {
    key = 'PageUp',
    mods = 'SHIFT',
    action = act.ScrollByPage(-1),
  },
  -- Scroll down one page
  {
    key = 'PageDown',
    mods = 'SHIFT',
    action = act.ScrollByPage(1),
  },
}

return config
​
pages
number
required
Number of pages to scroll. Negative values scroll up, positive scroll down. Supports fractional values for partial page scrolling (e.g., 0.5 for half a page)
Fractional page scrolling is supported since version 20220319-142410-0fcdea07

​
ScrollByLine

Scroll by individual lines: 
config.keys = {
  -- Scroll up one line
  {
    key = 'UpArrow',
    mods = 'SHIFT',
    action = act.ScrollByLine(-1),
  },
  -- Scroll down one line
  {
    key = 'DownArrow',
    mods = 'SHIFT',
    action = act.ScrollByLine(1),
  },
  -- Scroll up 5 lines
  {
    key = 'K',
    mods = 'CTRL|SHIFT',
    action = act.ScrollByLine(-5),
  },
}
​
lines
integer
required
Number of lines to scroll. Negative values scroll up, positive scroll down

​
ScrollByCurrentEventWheelDelta

Scroll based on the current mouse wheel event: 
config.mouse_bindings = {
  {
    event = { Down = { streak = 1, button = { WheelUp = 1 } } },
    mods = 'NONE',
    action = act.ScrollByCurrentEventWheelDelta,
  },
  {
    event = { Down = { streak = 1, button = { WheelDown = 1 } } },
    mods = 'NONE',
    action = act.ScrollByCurrentEventWheelDelta,
  },
}
This action uses the mouse wheel delta from the current event to determine how much to scroll.

​
Jump to Position

​
ScrollToTop

Scroll to the top of the scrollback: 
config.keys = {
  {
    key = 'Home',
    mods = 'SHIFT',
    action = act.ScrollToTop,
  },
}

​
ScrollToBottom

Scroll to the bottom (current output): 
config.keys = {
  {
    key = 'End',
    mods = 'SHIFT',
    action = act.ScrollToBottom,
  },
}

​
Semantic Scrolling

​
ScrollToPrompt

Navigate to shell prompts in the scrollback: 
config.keys = {
  -- Jump to previous prompt
  {
    key = 'UpArrow',
    mods = 'CTRL|SHIFT',
    action = act.ScrollToPrompt(-1),
  },
  -- Jump to next prompt
  {
    key = 'DownArrow',
    mods = 'CTRL|SHIFT',
    action = act.ScrollToPrompt(1),
  },
}
​
offset
integer
required
Number of prompts to jump. Negative values jump to previous prompts, positive to next prompts
This feature requires semantic prompt tracking to be enabled. Your shell must emit OSC 133 sequences for prompt marking. WezTerm’s built-in shell integration provides this automatically.
To enable shell integration, add this to your shell rc file:For bash:
source ~/.config/wezterm/shell-integration.bash
For zsh:
source ~/.config/wezterm/shell-integration.zsh

​
Managing Scrollback

​
ClearScrollback

Clear the scrollback buffer: 
config.keys = {
  -- Clear scrollback only
  {
    key = 'K',
    mods = 'CTRL|SHIFT',
    action = act.ClearScrollback 'ScrollbackOnly',
  },
  -- Clear scrollback and viewport
  {
    key = 'L',
    mods = 'CTRL|SHIFT',
    action = act.ClearScrollback 'ScrollbackAndViewport',
  },
}
​
mode
ScrollbackEraseMode
required
What to clear:
  • 'ScrollbackOnly' - Clear only the scrollback buffer, preserving the viewport (default)
  • 'ScrollbackAndViewport' - Clear both scrollback and viewport (like clear command)

​
Copy Mode Scrolling

When in copy mode, you can use dedicated copy mode scrolling actions: 
config.key_tables = {
  copy_mode = {
    -- Viewport navigation
    { key = 'g', mods = 'CTRL', action = act.CopyMode 'MoveToViewportTop' },
    { key = 'G', mods = 'SHIFT', action = act.CopyMode 'MoveToViewportBottom' },
    { key = 'H', mods = 'SHIFT', action = act.CopyMode 'MoveToViewportMiddle' },
    
    -- Scrollback navigation
    { key = 'g', action = act.CopyMode 'MoveToScrollbackTop' },
    { key = 'G', action = act.CopyMode 'MoveToScrollbackBottom' },
    
    -- Page scrolling
    { key = 'PageUp', action = act.CopyMode 'PageUp' },
    { key = 'PageDown', action = act.CopyMode 'PageDown' },
    { key = 'b', mods = 'CTRL', action = act.CopyMode 'PageUp' },
    { key = 'f', mods = 'CTRL', action = act.CopyMode 'PageDown' },
    
    -- Line scrolling
    { key = 'k', action = act.CopyMode 'MoveUp' },
    { key = 'j', action = act.CopyMode 'MoveDown' },
  },
}

​
Complete Example

local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {
  -- Page scrolling
  { key = 'PageUp', mods = 'SHIFT', action = act.ScrollByPage(-1) },
  { key = 'PageDown', mods = 'SHIFT', action = act.ScrollByPage(1) },
  
  -- Line scrolling
  { key = 'UpArrow', mods = 'SHIFT', action = act.ScrollByLine(-1) },
  { key = 'DownArrow', mods = 'SHIFT', action = act.ScrollByLine(1) },
  
  -- Jump to top/bottom
  { key = 'Home', mods = 'SHIFT', action = act.ScrollToTop },
  { key = 'End', mods = 'SHIFT', action = act.ScrollToBottom },
  
  -- Clear scrollback
  { key = 'K', mods = 'CTRL|SHIFT', action = act.ClearScrollback 'ScrollbackOnly' },
}

return config

​
Configuration Options

Related configuration options that affect scrolling behavior:
​
scrollback_lines
integer
default:"3500"
Number of lines of scrollback to keep in memory
​
enable_scroll_bar
boolean
default:"false"
Whether to show a scrollbar
​
min_scroll_bar_height
string
default:"'2cell'"
Minimum height of the scrollbar thumb
config.scrollback_lines = 10000
config.enable_scroll_bar = true
config.min_scroll_bar_height = '3cell'