Skip to main content

Normal mouse

AI-Generated Content
This page was generated with the assistance of AI and may contain inaccuracies. It is intended as a placeholder for future human verification. If you spot issues ahead of its initial review, please report them on GitHub!
Experimental

Normal Mouse Tracking (Mode 1000) is a DECSET/DECRST mode that enables reporting of mouse button press and release events to the application.

Syntax​

CSI ? 1000 h    DECSET — Enable normal mouse tracking
CSI ? 1000 l    DECRST — Disable normal mouse tracking
Formal syntax
DECSET-mode1000 = 0x1b, "[", "?", "1", "0", "0", "0", "h" ;
DECRST-mode1000 = 0x1b, "[", "?", "1", "0", "0", "0", "l" ;

Description​

Mode 1000 is an XTerm extension that enables basic mouse event reporting. When enabled, the terminal sends escape sequences to the application whenever a mouse button is pressed or released within the terminal window.

  • Set — The terminal reports mouse button press and release events.
  • Reset — Mouse events are not reported. The terminal handles mouse events normally (e.g., for text selection). This is the default.

Report format (X10 encoding)​

When a mouse event occurs, the terminal sends:

CSI M Cb Cx Cy

Where:

  • Cb is the button byte: the button number plus modifier flags, plus 32
  • Cx is the column (x coordinate) plus 32
  • Cy is the row (y coordinate) plus 32

The 32 offset ensures all values are printable ASCII characters (space and above).

Button encoding​

Value (Cb - 32)Meaning
0Left button press
1Middle button press
2Right button press
3Button release (any button)
64Scroll wheel up
65Scroll wheel down

Modifier keys are encoded as additional bit flags:

BitModifier
4Shift
8Meta/Alt
16Control

Limitations​

The X10/normal encoding has a fundamental limitation: because coordinates are encoded as single bytes with a +32 offset, the maximum reportable position is column/row 223 (255 - 32). For terminals wider or taller than 223, the SGR mouse encoding (Mode 1006) should be used instead.

note

Mode 1000 reports press and release events but does not report mouse motion. For motion tracking, use Mode 1002 (button-event tracking) or Mode 1003 (any-event tracking).

Examples​

printf '\e[?1000h'   # Enable normal mouse tracking
printf '\e[?1000l'   # Disable normal mouse tracking

# Typically combined with SGR encoding for better compatibility:
printf '\e[?1000h\e[?1006h'   # Enable mouse tracking with SGR encoding
printf '\e[?1006l\e[?1000l'   # Disable both (reverse order)

Specifications​

SpecificationSection
XTerm ctlseqs—

Terminal support​

TerminalSupportVersionNotes
Terminal Emulators
Alacritty✓Yes
Bobcat✓0.9.0Implemented in TerminalCtrl library. README states 'Full Mouse & Keyboard Support across all major protocols'.
contour✓v0.3.0.198Implemented as DECMode::MouseProtocolNormalTracking, handled in Terminal.cpp:2396
foot✓Yes
Ghostty✓v1.0.0
iTerm2✓v20260216-nightly
Kitty✓Yes
Konsole✓YesMODE_Mouse1000 for basic press/release tracking
mintty✓YesImplemented at src/termout.c:2487
mlterm✓rel-0_2_1Present since initial public release
PuTTY✓0.52
Rio✓v0.1.13
rxvt-unicode✓1.2
st✓0.3
terminology✓v0.2.0Sets mouse_mode to MOUSE_NORMAL
VT100✗No
VTE✓Yes
WezTerm✓Yes
Windows Terminal✓YesVT200_MOUSE_MODE at adaptDispatch.cpp:1847-1849
xterm✓YesX10 and VT200 mouse modes
xterm.js✓0.3
Multiplexers
cy✓Yes
GNU Screen✓v.4.2.0Present since at least v.4.0.2 (2005)
tmux✓1.7
tuios✓v0.0.15
Zellij✓v0.31.2

See also​