Skip to main content

SGR 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

SGR Mouse Encoding (Mode 1006) is a DECSET/DECRST mode that switches mouse event reports to an extended format using decimal parameters, removing the 223-coordinate limit of the original X10 encoding.

Syntax​

CSI ? 1006 h    DECSET — Enable SGR mouse encoding
CSI ? 1006 l    DECRST — Disable SGR mouse encoding (use X10 encoding)
Formal syntax
DECSET-mode1006 = 0x1b, "[", "?", "1", "0", "0", "6", "h" ;
DECRST-mode1006 = 0x1b, "[", "?", "1", "0", "0", "6", "l" ;

Description​

Mode 1006 is an XTerm extension that changes the encoding format used for mouse event reports. It does not enable mouse tracking on its own; it must be used in combination with a mouse tracking mode (Mode 1000, 1002, or 1003).

  • Set — Mouse events are reported using the SGR extended format.
  • Reset — Mouse events use the legacy X10 format (CSI M Cb Cx Cy). This is the default.

SGR report format​

When a mouse event occurs with SGR encoding enabled, the terminal sends:

CSI < Cb ; Cx ; Cy M    (button press or motion)
CSI < Cb ; Cx ; Cy m    (button release)

Where:

  • Cb is the button number (0-based) plus modifier flags, as a decimal string
  • Cx is the column (1-based), as a decimal string
  • Cy is the row (1-based), as a decimal string

The final character distinguishes press (M, uppercase) from release (m, lowercase).

Button encoding​

Button numbers in SGR encoding are 0-based:

Cb valueMeaning
0Left button
1Middle button
2Right button
32Motion (added as flag)
64Scroll wheel up
65Scroll wheel down

Modifier flags are the same as in X10 encoding:

BitModifier
4Shift
8Meta/Alt
16Control

Advantages over X10 encoding​

  • No coordinate limit — Coordinates are decimal strings, so they can represent any value. The X10 encoding encodes coordinates as single bytes with a +32 offset, limiting them to 223.
  • Distinct release events — The lowercase m final byte clearly identifies release events and indicates which button was released. In X10 encoding, all releases report button 3 with no way to distinguish which button was released.
  • 1-based coordinates — Coordinates are 1-based and directly correspond to terminal cell positions, avoiding the +32 offset.

Parsing​

A typical regex for parsing SGR mouse reports:

\e\[<(\d+);(\d+);(\d+)([Mm])

Group 1 is the button/flags, groups 2 and 3 are column and row, and group 4 indicates press (M) or release (m).

Examples​

# Enable mouse tracking with SGR encoding:
printf '\e[?1000h\e[?1006h'

# A left-button click at column 10, row 5 produces:
#   press:   \e[<0;10;5M
#   release: \e[<0;10;5m

# A Ctrl+click at column 300, row 100 produces:
#   press:   \e[<16;300;100M
#   release: \e[<16;300;100m

# Disable:
printf '\e[?1006l\e[?1000l'

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::MouseSGR at primitives.h:698, handled in Terminal.cpp:2367
foot✓Yes
Ghostty✓v1.0.0
iTerm2✓v20260216-nightly
Kitty✓Yes
Konsole✓YesMODE_Mouse1006 for SGR extended coordinates
mintty✓YesImplemented at src/termout.c:2501
mlterm✓rel-3_1_2
PuTTY✓0.63
Rio✓v0.1.13
rxvt-unicode✓9.25Requires ENABLE_FRILLS (default on)
st✓0.4
terminology✓v0.2.0Sets mouse_ext to MOUSE_EXT_SGR
VT100✗No
VTE✓Yes
WezTerm✓Yes
Windows Terminal✓YesSGR_EXTENDED_MODE at adaptDispatch.cpp:1859-1861
xterm✓YesSGR extended mouse coordinates
xterm.js✓2.0.1
Multiplexers
cy✓Yes
GNU Screen✓v.4.7.0Added in commit 40819ff (2018)
tmux✓1.8
tuios✓v0.0.15
Zellij✓v0.31.2

See also​