CUP Cursor Position
Move the cursor to a given line and column.
CSI Pl ; Pc H
- Defaults
- Pl = 1, Pc = 1
- ECMA-48
- §8.3.21 CUP – Cursor Position, p. 36
- DEC STD 070
- §5.4.4 Cursor Position, p. 5-49
- VT220
- §4.7 Cursor Positioning
- VT510
- CUP—Cursor Position
Move the cursor to line Pl, column Pc, both counting from 1. Either can be left out, and so can both: CSI H is the top-left corner. A 0 is taken as 1.
A position past the edge of the screen is clamped to it, so CSI 999 ; 999 H is a common way of reaching the bottom-right corner without knowing the size of the screen.
With origin mode (CSI ? 6 h, DECOM) on, the position counts from the top and left margins instead of the screen’s corner, and is clamped to the margins rather than to the screen.
Moving the cursor cancels any pending wrap, as DEC STD 070 asks (§D.6.1, p. D-13) and xterm’s CursorSet does. CSI Pl ; Pc f (HVP) does the same thing as CUP.
Support
| Terminal | Version | Support | Notes |
|---|---|---|---|
| VT220 | manual, 2nd ed., 1984 | Yes | §4.7 Cursor Positioning |
| VT510 | manual, 1st ed., 1993 | Yes | CUP |
| xterm | patch 412, xterm-411a | Yes | |
| libghostty-vt | 0f171f6 | Yes | |
| kitty | 0.49.1, run in a VM | Yes | passes the 3 cases that show it working |
| foot | 1.28.0, run in a VM | Yes | passes the 3 cases that show it working |
| pyte | 0.8.2, run as a library | Partly | fails CUP-4 of the 4 cases that show it working |
| xterm.js headless | 6.0.0, run as a library | Yes | passes the 4 cases that show it working |
| alacritty_terminal | 0.26.0, run as a library | Yes | passes the 4 cases that show it working |
| ConEmu | build 230724, its documentation | Yes | lists ESC [ row ; col H: ANSI escape codes |
| rxvt-unicode | 9.31, run in a VM | Yes | passes the 3 cases that show it working |
| VTE | 0.84.1, run as a library | Yes | passes the 4 cases that show it working |
Validation
CUP-1: To a position
\e[2;3H
X
|_____|
|__X__|
|_____|
CUP-2: Defaults
\e[3;3H
\e[H # both left out
A
\e[2H # column left out
B
\e[;4H # line left out
C
|A__C_|
|B____|
|_____|
CUP-3: Clamped to the screen
\e[999;999H
X
|_____|
|_____|
|____X|
cursor 3,5
pending-wrap yes
CUP-4: With origin mode
\e[2;3r # region is lines 2 and 3
\e[?6h # origin mode
\e[1;1H # the top of the region
A
\e[9;1H # clamped to the bottom of the region
B
|_____|
|A____|
|B____|
|_____|