Alt scroll
Alt Scroll (Mode 1007) is a DECSET/DECRST mode that translates scroll wheel events into cursor key sequences when the alternate screen buffer is active and mouse reporting is disabled.
Syntax
CSI ? 1007 h DECSET — Enable alternate scroll mode
CSI ? 1007 l DECRST — Disable alternate scroll mode
DECSET-mode1007 = 0x1b, "[", "?", "1", "0", "0", "7", "h" ; DECRST-mode1007 = 0x1b, "[", "?", "1", "0", "0", "7", "l" ;
Description
Mode 1007 is an XTerm extension that provides a convenient way to scroll through content in applications that use the alternate screen buffer (such as less, man, or vi) but do not enable mouse reporting.
- Set — When the alternate screen is active and no mouse tracking mode is enabled, scroll wheel up/down events are translated into cursor up/down key sequences.
- Reset — Scroll wheel events on the alternate screen are handled normally by the terminal (typically ignored if mouse reporting is off). This is the default.
Behavior
When all of the following conditions are met:
- Mode 1007 is enabled
- The alternate screen buffer is active (Mode 1049 or Mode 47)
- No mouse tracking mode is enabled (Modes 1000, 1002, 1003 are all reset)
Then scroll wheel events are translated as follows:
| Scroll event | Translated to |
|---|---|
| Wheel up | Cursor Up key (repeated) |
| Wheel down | Cursor Down key (repeated) |
The number of cursor key repetitions per scroll step is typically configurable in the terminal emulator's settings.
Common uses
This mode is particularly useful for applications like less and man that navigate with cursor keys but do not implement mouse reporting. Without Mode 1007, scroll wheel events on the alternate screen have no effect since there is no scrollback buffer to scroll through.
Many terminal emulators enable this behavior by default or provide a configuration option for it, independent of Mode 1007.
Examples
printf '\e[?1007h' # Enable alternate scroll mode
printf '\e[?1007l' # Disable alternate scroll mode
# Typical usage: enable before launching an alternate-screen application
printf '\e[?1007h'
less /var/log/syslog
printf '\e[?1007l'
Specifications
| Specification | Section |
|---|---|
| XTerm ctlseqs | — |
Terminal support
| Terminal | Support | Version | Notes |
|---|---|---|---|
| Terminal Emulators | |||
| Alacritty | ✓ | v0.4.0 | |
| Bobcat | ✓ | 0.9.0 | Implemented in TerminalCtrl library. Configurable via AlternateScroll setting. |
| contour | ✓ | v0.3.0.198 | Implemented as DECMode::MouseAlternateScroll at primitives.h:707, handled in Terminal.cpp:2386 |
| foot | ✓ | Yes | |
| Ghostty | ✓ | v1.0.0 | |
| iTerm2 | ✓ | v20260216-nightly | Can be restricted by delegate |
| Kitty | ✗ | No | |
| Konsole | ✓ | Yes | MODE_Mouse1007 for alternate scroll mode |
| mintty | ✓ | Yes | Implemented at src/termout.c:2587 |
| mlterm | ✗ | No | Permanently set (always enabled) according to get_vtmode() |
| PuTTY | ✗ | No | |
| Rio | ✓ | v0.1.13 | |
| rxvt-unicode | ✗ | No | |
| st | ✗ | No | |
| terminology | ✗ | No | |
| VT100 | ✗ | No | |
| VTE | ✓ | Yes | |
| WezTerm | ✗ | No | |
| Windows Terminal | ✓ | Yes | ALTERNATE_SCROLL at adaptDispatch.cpp:1870-1872 |
| xterm | ✓ | Yes | Alternate scroll mode |
| xterm.js | ✓ | 3.3.0 | Implemented in viewport, not as explicit mode toggle |
| Multiplexers | |||
| cy | ✗ | No | |
| GNU Screen | ✗ | No | |
| tmux | ✗ | No | |
| tuios | ✗ | No | |
| Zellij | ✗ | No | |
See also
- Alt Screen — Mode 1049 — Alternate screen buffer
- Normal Mouse Tracking — Mode 1000 — Mouse event reporting