Scrolling Key Actions

Key assignments for scrolling through terminal output and navigating scrollback in WezTerm

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

Basic Scrolling

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'

Related Actions

• Copy/Paste Actions - Copy text from scrollback
• Search Actions - Search through scrollback history