> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```lua theme={null}
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
```

<ParamField path="pages" type="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)
</ParamField>

<Note>
  Fractional page scrolling is supported since version 20220319-142410-0fcdea07
</Note>

### ScrollByLine

Scroll by individual lines:

```lua theme={null}
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),
  },
}
```

<ParamField path="lines" type="integer" required>
  Number of lines to scroll. Negative values scroll up, positive scroll down
</ParamField>

### ScrollByCurrentEventWheelDelta

Scroll based on the current mouse wheel event:

```lua theme={null}
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:

```lua theme={null}
config.keys = {
  {
    key = 'Home',
    mods = 'SHIFT',
    action = act.ScrollToTop,
  },
}
```

### ScrollToBottom

Scroll to the bottom (current output):

```lua theme={null}
config.keys = {
  {
    key = 'End',
    mods = 'SHIFT',
    action = act.ScrollToBottom,
  },
}
```

## Semantic Scrolling

### ScrollToPrompt

Navigate to shell prompts in the scrollback:

```lua theme={null}
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),
  },
}
```

<ParamField path="offset" type="integer" required>
  Number of prompts to jump. Negative values jump to previous prompts, positive to next prompts
</ParamField>

<Note>
  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.
</Note>

<Tip>
  To enable shell integration, add this to your shell rc file:

  For bash:

  ```bash theme={null}
  source ~/.config/wezterm/shell-integration.bash
  ```

  For zsh:

  ```zsh theme={null}
  source ~/.config/wezterm/shell-integration.zsh
  ```
</Tip>

## Managing Scrollback

### ClearScrollback

Clear the scrollback buffer:

```lua theme={null}
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',
  },
}
```

<ParamField path="mode" type="ScrollbackEraseMode" required>
  What to clear:

  * `'ScrollbackOnly'` - Clear only the scrollback buffer, preserving the viewport (default)
  * `'ScrollbackAndViewport'` - Clear both scrollback and viewport (like `clear` command)
</ParamField>

## Copy Mode Scrolling

When in copy mode, you can use dedicated copy mode scrolling actions:

```lua theme={null}
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

<CodeGroup>
  ```lua Basic Scrolling theme={null}
  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
  ```

  ```lua Vim-Style Scrolling theme={null}
  local wezterm = require 'wezterm'
  local act = wezterm.action
  local config = {}

  config.keys = {
    -- Half-page scrolling
    { key = 'u', mods = 'CTRL', action = act.ScrollByPage(-0.5) },
    { key = 'd', mods = 'CTRL', action = act.ScrollByPage(0.5) },
    
    -- Full page scrolling
    { key = 'b', mods = 'CTRL', action = act.ScrollByPage(-1) },
    { key = 'f', mods = 'CTRL', action = act.ScrollByPage(1) },
    
    -- Jump to top/bottom
    { key = 'g', mods = 'CTRL', action = act.ScrollToTop },
    { key = 'G', mods = 'CTRL|SHIFT', action = act.ScrollToBottom },
  }

  return config
  ```

  ```lua Semantic Navigation theme={null}
  local wezterm = require 'wezterm'
  local act = wezterm.action
  local config = {}

  config.keys = {
    -- Navigate by prompts
    {
      key = 'UpArrow',
      mods = 'CTRL|SHIFT',
      action = act.ScrollToPrompt(-1),
    },
    {
      key = 'DownArrow',
      mods = 'CTRL|SHIFT',
      action = act.ScrollToPrompt(1),
    },
    
    -- Vim-style prompt navigation
    {
      key = 'k',
      mods = 'CTRL|SHIFT',
      action = act.ScrollToPrompt(-1),
    },
    {
      key = 'j',
      mods = 'CTRL|SHIFT',
      action = act.ScrollToPrompt(1),
    },
    
    -- Regular scrolling
    { key = 'PageUp', mods = 'SHIFT', action = act.ScrollByPage(-1) },
    { key = 'PageDown', mods = 'SHIFT', action = act.ScrollByPage(1) },
  }

  return config
  ```

  ```lua Mouse Wheel Scrolling theme={null}
  local wezterm = require 'wezterm'
  local act = wezterm.action
  local config = {}

  config.mouse_bindings = {
    -- Regular mouse wheel
    {
      event = { Down = { streak = 1, button = { WheelUp = 1 } } },
      mods = 'NONE',
      action = act.ScrollByCurrentEventWheelDelta,
    },
    {
      event = { Down = { streak = 1, button = { WheelDown = 1 } } },
      mods = 'NONE',
      action = act.ScrollByCurrentEventWheelDelta,
    },
    
    -- Ctrl+wheel for faster scrolling
    {
      event = { Down = { streak = 1, button = { WheelUp = 1 } } },
      mods = 'CTRL',
      action = act.ScrollByLine(-5),
    },
    {
      event = { Down = { streak = 1, button = { WheelDown = 1 } } },
      mods = 'CTRL',
      action = act.ScrollByLine(5),
    },
  }

  return config
  ```
</CodeGroup>

## Configuration Options

Related configuration options that affect scrolling behavior:

<ParamField path="scrollback_lines" type="integer" default="3500">
  Number of lines of scrollback to keep in memory
</ParamField>

<ParamField path="enable_scroll_bar" type="boolean" default="false">
  Whether to show a scrollbar
</ParamField>

<ParamField path="min_scroll_bar_height" type="string" default="'2cell'">
  Minimum height of the scrollbar thumb
</ParamField>

```lua theme={null}
config.scrollback_lines = 10000
config.enable_scroll_bar = true
config.min_scroll_bar_height = '3cell'
```

## Related Actions

* [Copy/Paste Actions](/lua/keyassignment/copy-paste) - Copy text from scrollback
* [Search Actions](/lua/keyassignment/search) - Search through scrollback history