DECSET 1000 — Mouse tracking (normal / X11 button-event)

CSI ? 1000 h enables 'normal' mouse tracking: the terminal reports mouse button press and release as CSI M Cb Cx Cy, where each coordinate byte is (value + 32). CSI ? 1000 l disables it. This is the baseline X11 mouse protocol; higher modes (1002 button-motion, 1003 any-motion) and encodings (1006 SGR) build on it.

aka: mouse tracking · X11 mouse · normal mouse mode · DECSET 1000 · ?1000h / ?1000l · button-event tracking

frame

DEC-private-mode introducer: \x1b[? ESC [ ? (0x1B 0x5B 0x3F)

terminator (none): ST · BEL

parameters / subcommands

id	name	bytes (ST)	meaning
set	Enable (DECSET)	\x1b[?1000h	CSI ? 1000 h turns on normal (button press/release) mouse tracking. The terminal then reports clicks; with the default encoding the report is CSI M Cb Cx Cy where Cb encodes the button+modifiers and Cx,Cy are column,row, each as a single byte = (value + 32).
reset	Disable (DECRST)	\x1b[?1000l	CSI ? 1000 l turns off mouse tracking.
report	Default report format (terminal -> app)	\x1b[M	Under mode 1000 with the legacy encoding, a button event is reported as CSI M followed by three bytes: Cb (button + modifier bits, +32), Cx (column, +32), Cy (row, +32). Example: button 1 press at column 1, row 1 = ESC [ M space space space (0x20 0x20 0x20).

gotchas

Legacy encoding is byte-based with a +32 offset, so coordinates above 223 (255-32) cannot be represented and bytes can collide with UTF-8 — this is exactly why the SGR encoding (mode 1006) exists. Prefer enabling 1000 (or 1002/1003) TOGETHER with 1006.
1000 reports press AND release but not motion. For drag (motion while a button is held) enable 1002; for all motion enable 1003.
Modes are layered: 1000/1002/1003 select WHICH events are reported; 1005 (UTF-8), 1006 (SGR), 1015 (urxvt) select HOW they are ENCODED. Enable one tracking mode and one encoding mode.
Always disable mouse tracking (?1000l, and the encoding mode) on exit, or the user's normal click-to-select/copy is left hijacked.
While mouse tracking is on, the terminal's own text-selection is usually suppressed; users hold a modifier (often Shift) to bypass and select normally.

provenance

source: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
version: xterm ctlseqs, patch #410, 2026/04/19
retrieved: 2026-05-29 · updated: 2026-05-29T00:00:00Z

per-fact attribution:

#summary — https://invisible-island.net/xterm/ctlseqs/ctlseqs.html xterm ctlseqs 'Mouse Tracking': Ps = 1 0 0 0 -> Send Mouse X & Y on button press and release (X11 xterm mouse protocol). Default report is CSI M CbCxCy with each value offset by 32 (0x20).

DECSET 1000 — Mouse tracking (normal / X11 button-event)

frame

parameters / subcommands

gotchas

provenance

see also