Skip to main content

DECSTBM

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

DECSTBM (Set Top and Bottom Margins) is a CSI sequence that defines the vertical scrolling region. Operations such as IND, RI, SU, SD, IL, and DL are confined to the lines within these margins.

Syntax​

CSI Pt ; Pb r     DECSTBM — Set Top and Bottom Margins
Formal syntax
DECSTBM = 0x1b, "[", [ Pt, [ ";", Pb ] ], "r" ;
Pt = digit, { digit } ;                 (* top margin, default: 1 *)
Pb = digit, { digit } ;                 (* bottom margin, default: screen height *)
digit = "0" | "1" | "2" | "3" | "4"
    | "5" | "6" | "7" | "8" | "9" ;

Parameters​

ParameterDescriptionDefault
PtTop margin (first scrolling line)1
PbBottom margin (last scrolling line)Screen height

Description​

Per the VT510 manual, DECSTBM defines the top and bottom lines of the scrolling region. Pt must be less than Pb, and both must be within the screen dimensions. CSI r with no parameters resets the margins to the full screen.

After setting margins:

  • The cursor moves to the home position. If DECOM (Origin Mode) is set, home is the top-left of the scrolling region; otherwise, it is row 1, column 1 of the screen.
  • Scrolling operations (IND, RI, SU, SD, LF at bottom margin) are confined to the margin area.
  • IL and DL operate within the scrolling region.
  • CUP and other absolute positioning commands are not affected by the margins (unless DECOM is set).

Common uses​

DECSTBM is fundamental to full-screen TUI applications. For example:

  • Status bars: Set margins to exclude the top or bottom line, then write the status bar outside the scrolling region.
  • Split views: Create multiple independent scrolling areas by switching margins programmatically.

Examples​

printf '\e[5;20r'    # Set scrolling region to lines 5-20
printf '\e[r'        # Reset scrolling region to full screen

Specifications​

SpecificationSection
VT510 Reference—

Terminal support​

TerminalSupportVersionNotes
Terminal Emulators
Alacritty✓0.1.0Implemented via set_scrolling_region method
Bobcat✓0.9.0Supported via TerminalCtrl library
contour✓v0.1.0
foot✓YesDECSTBM (r) at csi.c:1232-1248
Ghostty✓v1.0.0
iTerm2✓YesVT100CSI_DECSTBM token parsed and executed with top/bottom margin setting via terminalSetScrollRegionTop:bottom:
Kitty✓YesDECSTBM (CSI r) fully implemented in vt-parser.c:1327-1329, screen.c:2836-2851
Konsole✓YesDECSTBM (CSI r) sets top/bottom margins at src/Vt102Emulation.cpp:2156
mintty✓YesDECSTBM (CSI r) at line 3380-3389, sets top and bottom scroll margins
mlterm✓rel-2_9_0Implemented at vt_parser.c:5866-5878
PuTTY✓0.45
Rio✓v0.0.3
rxvt-unicode✓1.2
st✓0.1
terminology✓v0.1.0
VT100✓Yes
VTE✓YesFully implemented in vteseq.cc as DECSTBM handler
WezTerm✓YesDECSTBM implemented as Cursor::SetTopAndBottomMargins
Windows Terminal✓YesImplemented in ITermDispatch.hpp:74 as SetTopBottomScrollingMargins (DECSTBM)
xterm✓xterm-406
xterm.js✓2.3.0
Multiplexers
cy✓v0.1.0
GNU Screen✓v.4.2.0
tmux✓1.6DECSTBM (CSI r) implemented for top/bottom margins
tuios✓v0.0.15
Zellij✓v0.1.0-alpha

See also​