CHA/CUP

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!

Standard

CHA (Cursor Character Absolute) and CUP (Cursor Position) are CSI sequences for absolute cursor positioning. CHA sets the column, while CUP sets both the row and column.

Syntax

CSI Pn G          CHA — Cursor Character Absolute (set column)
CSI Pn1 ; Pn2 H   CUP — Cursor Position (set row and column)

Formal syntax

CHA = 0x1b, "[", [ Pn ], "G" ;
CUP = 0x1b, "[", [ Pn1, [ ";", Pn2 ] ], "H" ;
Pn  = digit, { digit } ;                (* default: 1 *)
Pn1 = digit, { digit } ;                (* row, default: 1 *)
Pn2 = digit, { digit } ;                (* column, default: 1 *)
digit = "0" | "1" | "2" | "3" | "4"
    | "5" | "6" | "7" | "8" | "9" ;

Parameters

CHA:

Parameter	Description	Default
`Pn`	Column number	1

CUP:

Parameter	Description	Default
`Pn1`	Row number	1
`Pn2`	Column number	1

Description

Per ECMA-48 §8.3.9 (CHA) and §8.3.21 (CUP):

CHA (CSI Pn G) — Moves the cursor to column Pn of the current line. The row does not change.
CUP (CSI Pn1;Pn2 H) — Moves the cursor to row Pn1, column Pn2. CSI H with no parameters moves to the home position (row 1, column 1).

Positions are 1-based. Values exceeding the screen dimensions are clamped to the maximum row or column.

Interaction with DECOM

When Origin Mode (DECOM) is set, CUP coordinates are relative to the top margin of the scrolling region rather than to the top of the screen, and the cursor is constrained within the scrolling region. When DECOM is reset (the default), coordinates are absolute from the top-left of the screen.

Examples

printf '\e[1;1H'     # Move to top-left corner (home)
printf '\e[H'        # Same — move to home (defaults)
printf '\e[10;20H'   # Move to row 10, column 20
printf '\e[5G'       # Move to column 5 on current line

Specifications

Specification	Section
ECMA-48	—

Terminal support

Terminal	Support	Version	Notes
Terminal Emulators
Alacritty	✓	0.1.0	Implemented via goto/goto_line/goto_col methods
Bobcat	✓	0.9.0	Supported via TerminalCtrl library
contour	✓	v0.1.0
foot	✓	Yes	CHA (G/`) at csi.c:946-952, CUP (H/f) at csi.c:954-962
Ghostty	✓	v1.0.0
iTerm2	✓	Yes	ANSICSI_CHA and VT100CSI_CUP tokens parsed and executed via terminalSetCursorX and terminalMoveCursorToX:y:
Kitty	✓	Yes	CHA/CUP (CSI G/H) and HPA (CSI `) fully implemented in vt-parser.c:1208-1219
Konsole	✓	Yes	CHA (G), CUP (H) implemented at src/Vt102Emulation.cpp:2130-2131
mintty	✓	Yes	CHA (CSI G) and HPA (CSI `) at line 3165-3170, CUP/HVP (CSI H/f) at line 3175-3178
mlterm	✓	rel-2_9_0	Implemented at vt_parser.c:5616-5638
PuTTY	✓	0.45
Rio	✓	v0.0.3
rxvt-unicode	✓	1.2
st	✓	0.1
terminology	✓	v0.1.0
VT100	~	Yes	CUP only (CHA is ECMA-48)
VTE	✓	Yes	Fully implemented in vteseq.cc as CHA/CUP handlers
WezTerm	✓	Yes	CHA (CharacterAbsolute) and CUP (Position) implemented as Cursor::CharacterAbsolute and Cursor::Position
Windows Terminal	✓	Yes	CHA at ITermDispatch.hpp:47, CUP at line 51. Both absolute positioning methods implemented.
xterm	✓	xterm-406
xterm.js	✓	2.3.0
Multiplexers
cy	✓	v0.1.0
GNU Screen	✓	v.4.2.0
tmux	✓	1.6	CHA (CSI G) and CUP (CSI H) both supported
tuios	✓	v0.0.15
Zellij	✓	v0.1.0-alpha	CHA (CSI G) added in v0.1.0-alpha, CUP (CSI H) added in v0.1.0-alpha, alternative form (CSI f) added in v0.6.0

Syntax​

Parameters​

Description​

Interaction with DECOM​

Examples​

Specifications​

Terminal support​

See also​