Home Explore Blog CI



neovim

3rd chunk of `runtime/doc/tui.txt`
d43e8b27436555fd44d863ca28090bb3424110b8f7e56c010000000100000eb2
 methods and at startup will tell the terminal emulator that it
understands these key encodings. If your terminal emulator supports it then
this 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| (including
extended 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 and
go 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-modifyOtherKeys* *tui-csiu*
At 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 your
terminal 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 the
special key encoding. If Nvim does not exit cleanly then your terminal
emulator could be in a bad state. If this happens, simply run "reset".

							*tui-colors*
Nvim uses 256 colours by default, ignoring |terminfo| for most terminal types,
including "linux" (whose virtual terminals have had 256-colour support since
4.8) and anything claiming to be "xterm".  Also when $COLORTERM or $TERM
contain the string "256".

Nvim similarly assumes that any terminal emulator that sets $COLORTERM to any
value, is capable of at least 16-colour operation.

						*true-color* *xterm-true-color*
Nvim emits true (24-bit) colours in the terminal, if 'termguicolors' is set.

It uses the "setrgbf" and "setrgbb" |terminfo| extensions (proposed by Rüdiger
Sonderfeld in 2013). If your terminfo definition is missing them, then Nvim
will decide whether to add them to your terminfo definition, using the ISO
8613-6:1994/ITU T.416:1993 control sequences for setting RGB colours (but
modified to use semicolons instead of colons unless the terminal is known to
follow 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 and
other 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 emulator
version 0.36 or later, or a terminal emulator that sets the COLORTERM
environment variable to "truecolor" is detected.

							*xterm-resize*
Nvim can resize the terminal display on some terminals that implement an
extension pioneered by dtterm.  |terminfo| does not have a flag for this
extension.  So Nvim simply assumes that (all) "dtterm", "xterm", "teraterm",
"rxvt" terminal types, and Konsole, are capable of this.

							*tui-cursor-shape*
Nvim will adjust the shape of the cursor from a block to a line when in insert
mode (or as specified by the 'guicursor' option), on terminals that

Title: Nvim Terminal UI: Key Encoding, Color Support, and Terminal Resizing
Summary
This section elaborates on Nvim's terminal UI features, covering key encoding methods like 'CSI u' and 'modifyOtherKeys', how Nvim negotiates these with the terminal, and what happens if the negotiation fails. It also details Nvim's default use of 256 colors, its approach to true color support via 'termguicolors', and how it handles missing 'setrgbf' and 'setrgbb' terminfo extensions. Finally, it touches upon Nvim's ability to resize the terminal on certain emulators and adjust the cursor shape based on the current mode.