Tui
Nvim:help pages,generated fromsource using thetree-sitter-vimdoc parser.
By default when you run
nvim (without
--embed or
--headless) it startsthe builtin "terminal UI" (TUI). This default UI is optional: you can run Nvimas a "headless" server, or you can use a
GUI.
Nvim has a client-server architecture: by default when you run
nvim, thisstarts the builtin UI client, which starts a
nvim --embed server (child)process that the UI client connects to. After attaching to the server, the UIclient calls
nvim_set_client_info() (as recommended for all UIs
dev-ui)and sets these fields on its channel:
client = { attributes = { license = 'Apache 2', pid = …, website = 'https://neovim.io', }, name = 'nvim-tui', type = 'ui', version = { … },}Nvim guesses the terminal type when it starts (except in
--embed and
--headless modes). The
$TERM environment variable is the primary hint thatdetermines the terminal type.
terminfoE557E558E559To display its user interface, Nvim reads a list of "terminal capabilities"from the system terminfo database (or builtin defaults if terminfo is notfound). If that information is wrong, the screen may be messed up or keys maynot be recognized.
The Unibilium library (used to read terminfo) allows you to override thesystem terminfo with one in the "$HOME/.terminfo/" directory. Building yourown terminfo is usually as simple as running this:
curl -LO https://invisible-island.net/datafiles/current/terminfo.src.gzgunzip terminfo.src.gztic -x terminfo.src
$TERMThe $TERM environment variable must match the terminal you are using!Otherwise Nvim cannot know what sequences your terminal expects, and weirdor sub-optimal behavior will result (scrolling quirks, wrong colors, etc.).
$TERM is also important because it is forwarded by SSH to the remote session,unlike most other environment variables.
For this terminal Set $TERM to |builtin-terms|-------------------------------------------------------------------------anything libvte-based vte, vte-256color Y (e.g. GNOME Terminal) (aliases: gnome, gnome-256color)iTerm (original) iterm, iTerm.app NiTerm2 (new capabilities) iterm2, iTerm2.app YKonsole konsole-256color NLinux virtual terminal linux, linux-256color YPuTTY putty, putty-256color Yrxvt rxvt, rxvt-256color Yscreen screen, screen-256color Ysimple terminal (st) st, st-256color YTerminal.app nsterm Ntmux tmux, tmux-256color YWindows/ConEmu conemu YWindows/Cygwin-built Nvim cygwin YWindows/Interix interix YWindows/VTP console vtpcon YWindows/legacy console win32con Yxterm or compatible xterm, xterm-256color Y
builtin-termsbuiltin_termsIf a
terminfo database is not available or there is no entry for the currentterminal, Nvim will map
$TERM to a builtin entry according to the abovetable, or "ansi" if there is no match. For example "TERM=putty-256color" willbe mapped to the builtin "putty" entry. See also
tui-colors.
The builtin terminfo is not combined with any external terminfo database, norcan it be used in preference to one. You can thus entirely override anyomissions or out-of-date information in the builtin terminfo database bysupplying an external one with entries for the terminal type.
If you want to set terminal-dependent options or mappings, you can do this inyour init.vim. Example:
if $TERM =~ '^\(rxvt\|screen\|interix\|putty\)\(-.*\)\?$' set notermguicolorselseif $TERM =~ '^\(tmux\|iterm\|vte\|gnome\)\(-.*\)\?$' set termguicolorselseif $TERM =~ '^\(xterm\)\(-.*\)\?$' if $XTERM_VERSION != '' set termguicolors elseif $KONSOLE_PROFILE_NAME != '' set termguicolors elseif $VTE_VERSION != '' set termguicolors else set notermguicolors endifelseif $TERM =~ ... ... and so forth ...endif
scroll-regionxterm-scroll-regionWhere possible, Nvim will use the terminal's ability to set a scroll region inorder to redraw faster when a window is scrolled. If the terminal's terminfodescription describes an ability to set top and bottom scroll margins, that isused.
This will not speed up scrolling in a window that is not the full width of theterminal. Xterm has an extra ability, not described by terminfo, to set leftand right scroll margins as well. If Nvim detects that the terminal is Xterm,it will make use of this ability to speed up scrolling that is not the fullwidth of the terminal.
tui-inputHistorically, terminal emulators could not distinguish between certain controlkey modifiers and other keys. For example,
<C-I> and
<Tab> are represented inthe same way, as are
<Esc> and
<C-[>,
<CR> and
<C-M>, and
<NL> and
<C-J>.
Modern terminal emulators are able to distinguish between these pairs of keysby encoding control modifiers differently. There are two common but distinctways of doing this, known as "modifyOtherKeys" and "CSI u". Nvim supports bothencoding methods and at startup will tell the terminal emulator that itunderstands these key encodings. If your terminal emulator supports it thenthis will allow you to map the key pairs listed above separately.
<Tab>Nvim uses libtermkey to convert terminal escape sequences to key codes.
terminfo is used first, and CSI sequences not in
terminfo (includingextended keys a.k.a. "modifyOtherKeys" or "CSI u") can also be parsed.
For example, when running Nvim in tmux, this makes Nvim leave Insert mode andgo to the window below:
tmux send-keys 'Escape' [ 2 7 u 'C-W' j
Where
'Escape' [ 2 7 u is an unambiguous "CSI u" sequence for the
<Esc> key.
The kitty keyboard protocol
https://sw.kovidgoyal.net/kitty/keyboard-protocol/is partially supported, including keypad keys in Unicode Private Use Area.For example, this sequence is recognized by Nvim as
<C-kEnter>:
CSI 57414 ; 5 u
and can be used differently from
<C-CR> in mappings.
tui-modifyOtherKeystui-csiuAt startup Nvim will query your terminal to see if it supports the "CSI u"encoding by writing the sequence
CSI ? u CSI c
If your terminal emulator responds with
CSI ? <flags> u
this means your terminal supports the "CSI u" encoding and Nvim will tell yourterminal to enable it by writing the sequence
CSI > 1 u
If your terminal does not support "CSI u" then Nvim will instead enable the"modifyOtherKeys" encoding by writing the sequence
CSI > 4 ; 2 m
When Nvim exits cleanly it will send the corresponding sequence to disable thespecial key encoding. If Nvim does not exit cleanly then your terminalemulator could be in a bad state. If this happens, simply run "reset".
tui-colorsNvim uses 256 colours by default, ignoring
terminfo for most terminal types,including "linux" (whose virtual terminals have had 256-colour support since4.8) and anything claiming to be "xterm". Also when $COLORTERM or $TERMcontain the string "256".
Nvim similarly assumes that any terminal emulator that sets $COLORTERM to anyvalue, is capable of at least 16-colour operation.
It uses the "setrgbf" and "setrgbb"
terminfo extensions (proposed by RüdigerSonderfeld in 2013). If your terminfo definition is missing them, then Nvimwill decide whether to add them to your terminfo definition, using the ISO8613-6:1994/ITU T.416:1993 control sequences for setting RGB colours (butmodified to use semicolons instead of colons unless the terminal is known tofollow the standard).
Another convention, pioneered in 2016 by tmux, is the "Tc" terminfo extension.If terminfo has this flag, Nvim will add constructed "setrgbf" and "setrgbb"capabilities as if they had been in the terminfo definition.
If terminfo does not (yet) have this flag, Nvim will fall back to $TERM andother environment variables. It will add constructed "setrgbf" and "setrgbb"capabilities in the case of the "rxvt", "linux", "st", "tmux", and "iterm"terminal types, or when Konsole, genuine Xterm, a libvte terminal emulatorversion 0.36 or later, or a terminal emulator that sets the COLORTERMenvironment variable to "truecolor" is detected.
xterm-resizeNvim can resize the terminal display on some terminals that implement anextension pioneered by dtterm.
terminfo does not have a flag for thisextension. So Nvim simply assumes that (all) "dtterm", "xterm", "teraterm","rxvt" terminal types, and Konsole, are capable of this.
tui-cursor-shapeNvim will adjust the shape of the cursor from a block to a line when in insertmode (or as specified by the
'guicursor' option), on terminals that supportit. It uses the same
terminfo extensions that were pioneered by tmux forthis: "Ss" and "Se".Similarly, if you set the cursor highlight group with blend=100, Nvim hidesthe cursor through the "cvvis" and "civis" extensions.
If your terminfo definition is missing them, then Nvim will decide whether toadd them to your terminfo definition, by looking at $TERM and otherenvironment variables. For the "rxvt", "putty", "linux", "screen","teraterm", and "iterm" terminal types, or when Konsole, a libvte-basedterminal emulator, or genuine Xterm are detected, it will add constructed"Ss" and "Se" capabilities.
tui-cursor-tmuxWithin tmux it may appear that Nvim is not changing the cursor, but in fact itis tmux receiving instructions from Nvim to change the cursor and not knowingwhat to do in turn. tmux must translate what it receives from Nvim intowhatever control sequence is appropriate for the host terminal. It sharesa common mechanism with Nvim, of using the "Ss" and "Se" capabilities fromterminfo (for the output terminal) if they are present. Unlike Nvim, if theyare not in terminfo you must add them by setting "terminal-overrides" in~/.tmux.conf .
See the tmux(1) manual page for the details of how and what to do in the tmuxconfiguration file. It will look something like:
set -ga terminal-overrides '*:Ss=\E[%p1%d q:Se=\E[ q'
or (alas!) for Konsole 18.07.70 or older, something more complex like:
set -ga terminal-overrides 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007'
[This is about the size of the whole window Vim is using, not a window that iscreated with the ":split" command.]
On Unix systems, three methods are tried to get the window size:
an ioctl call (TIOCGSIZE or TIOCGWINSZ, depends on your system)
the environment variables "LINES" and "COLUMNS"
from the
terminfo entries "lines" and "columns"
If everything fails a default size of 24 lines and 80 columns is assumed. Ifa window-resize signal is received the size will be set again. If the windowsize is wrong you can use the
'lines' and
'columns' options to set thecorrect values. See
:mode.
If you have a slow terminal you may want to reset the
'showcmd' and
'ruler'options. The command characters and cursor positions will not be shown in thestatus line (which involves a lot of cursor motions and attribute changes forevery keypress or movement). If the terminal scrolls very slowly, set the
'scrolljump' to 5 or so. If the cursor is moved off the screen (e.g., with"j") Vim will scroll 5 lines at a time. Another possibility is to reduce thenumber of lines that Vim uses with the command "z{height}<CR>".
If the characters from the terminal are arriving with more than 1 secondbetween them you might want to set the
'timeout' and/or
'ttimeout' option.
If you are using a color terminal that is slow when displaying lines beyondthe end of a buffer, this is because Nvim is drawing the whitespace twice, intwo sets of colours and attributes. To prevent this, use this command:
hi NonText cterm=NONE ctermfg=NONE
This draws the spaces with the default colours and attributes, which allows thesecond pass of drawing to be optimized away.
Note: Although in theory thecolours of whitespace are immaterial, in practice they change the colours ofcursors and selections that cross them. This may have a visible, but minor,effect on some UIs.