Nvim :help
pages, generated
from source
using the tree-sitter-vimdoc parser.
tui
nvim
(without --embed or --headless) it starts
the builtin "terminal UI" (TUI). This default UI is optional: you can run Nvim
as a "headless" server, or you can use a GUI.
nvim
, this
starts the builtin UI client, which starts a nvim --embed
server (child)
process that the UI client connects to. After attaching to the server, the UI
client 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 that determines the terminal type.
terminfo
E557
E558
E559
To display its user interface, Nvim reads a list of "terminal capabilities"
from the system terminfo database (or builtin defaults if terminfo is not
found). If that information is wrong, the screen may be messed up or keys may
not be recognized.
curl -LO https://invisible-island.net/datafiles/current/terminfo.src.gz gunzip terminfo.src.gz tic -x terminfo.src
$TERM
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 N iTerm2 (new capabilities) iterm2, iTerm2.app Y Konsole konsole-256color N Linux virtual terminal linux, linux-256color Y PuTTY putty, putty-256color Y rxvt rxvt, rxvt-256color Y screen screen, screen-256color Y simple terminal (st) st, st-256color Y Terminal.app nsterm N tmux tmux, tmux-256color Y Windows/ConEmu conemu Y Windows/Cygwin-built Nvim cygwin Y Windows/Interix interix Y Windows/VTP console vtpcon Y Windows/legacy console win32con Y xterm or compatible xterm, xterm-256color Y
builtin-terms
builtin_terms
If a terminfo database is not available or there is no entry for the current
terminal, Nvim will map $TERM to a builtin entry according to the above
table, or "ansi" if there is no match. For example "TERM=putty-256color" will
be mapped to the builtin "putty" entry. See also tui-colors.
term-dependent-settings
if $TERM =~ '^\(rxvt\|screen\|interix\|putty\)\(-.*\)\?$'
set notermguicolors
elseif $TERM =~ '^\(tmux\|iterm\|vte\|gnome\)\(-.*\)\?$'
set termguicolors
elseif $TERM =~ '^\(xterm\)\(-.*\)\?$'
if $XTERM_VERSION != ''
set termguicolors
elseif $KONSOLE_PROFILE_NAME != ''
set termguicolors
elseif $VTE_VERSION != ''
set termguicolors
else
set notermguicolors
endif
elseif $TERM =~ ...
... and so forth ...
endif
scroll-region
xterm-scroll-region
Where possible, Nvim will use the terminal's ability to set a scroll region in
order to redraw faster when a window is scrolled. If the terminal's terminfo
description describes an ability to set top and bottom scroll margins, that is
used.
tui-input
<C-I>
and <Tab>
are represented in
the same way, as are <Esc>
and <C-[>
, <CR>
and <C-M>
, and <NL>
and <C-J>
.
tmux send-keys 'Escape' [ 2 7 u 'C-W' jWhere
'Escape' [ 2 7 u
is an unambiguous "CSI u" sequence for the <Esc>
key.
<C-kEnter>
:CSI 57414 ; 5 uand 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 sequenceCSI ? u CSI cIf your terminal emulator responds with
CSI ? <flags> uthis means your terminal supports the "CSI u" encoding and Nvim will tell your terminal to enable it by writing the sequence
CSI > 1 uIf your terminal does not support "CSI u" then Nvim will instead enable the "modifyOtherKeys" encoding by writing the sequence
CSI > 4 ; 2 mWhen 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
true-color
xterm-true-color
Nvim emits true (24-bit) colours in the terminal, if 'termguicolors' is set.
xterm-resize
tui-cursor-shape
tui-cursor-tmux
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'
hi NonText cterm=NONE ctermfg=NONE
This draws the spaces with the default colours and attributes, which allows the
second pass of drawing to be optimized away. Note: Although in theory the
colours of whitespace are immaterial, in practice they change the colours of
cursors and selections that cross them. This may have a visible, but minor,
effect on some UIs.
mouse-mode-table
mouse-overview
Overview of what the mouse buttons do, when 'mousemodel' is "extend":
<S-LeftMouse>
<A-RightMouse>
<S-RightMouse>
<RightDrag>
<RightRelease>
<LeftDrag>
Normal Mode:event position selection change action cursor window --------------------------------------------------------------------------- <LeftMouse> yes end yes <C-LeftMouse> yes end yes "CTRL-]" (2) <S-LeftMouse> yes no change yes "*" (2) <LeftDrag> yes start or extend (1) no <LeftRelease> yes start or extend (1) no <MiddleMouse> yes if not active no put <MiddleMouse> yes if active no yank and put <RightMouse> yes start or extend yes <A-RightMouse> yes start or extend blockw. yes <S-RightMouse> yes no change yes "#" (2) <C-RightMouse> no no change no "CTRL-T" <RightDrag> yes extend no <RightRelease> yes extend noInsert or Replace Mode:
event position selection change action cursor window --------------------------------------------------------------------------- <LeftMouse> yes (cannot be active) yes <C-LeftMouse> yes (cannot be active) yes "CTRL-O^]" (2) <S-LeftMouse> yes (cannot be active) yes "CTRL-O*" (2) <LeftDrag> yes start or extend (1) no like CTRL-O (1) <LeftRelease> yes start or extend (1) no like CTRL-O (1) <MiddleMouse> no (cannot be active) no put register <RightMouse> yes start or extend yes like CTRL-O <A-RightMouse> yes start or extend blockw. yes <S-RightMouse> yes (cannot be active) yes "CTRL-O#" (2) <C-RightMouse> no (cannot be active) no "CTRL-O CTRL-T"In a help window:
event position selection change action cursor window --------------------------------------------------------------------------- <2-LeftMouse> yes (cannot be active) no "^]" (jump to help tag)When 'mousemodel' is "popup", these are different:
<A-LeftMouse>
event position selection change action cursor window --------------------------------------------------------------------------- <S-LeftMouse> yes start or extend (1) no <A-LeftMouse> yes start/extend blockw no <RightMouse> no popup menu noInsert or Replace Mode:
event position selection change action cursor window --------------------------------------------------------------------------- <S-LeftMouse> yes start or extend (1) no like CTRL-O (1) <A-LeftMouse> yes start/extend blockw no <RightMouse> no popup menu no(1) only if mouse pointer moved since press (2) only if click is in same buffer
double-click
<2-LeftMouse>
<3-LeftMouse>
<4-LeftMouse>
Double, triple and quadruple clicks are supported when the GUI is active, for
Win32 and for an xterm. For selecting text, extra clicks extend the
selection:click select --------------------------------- double word or % match triple line quadruple rectangular blockException: In a Help window a double click jumps to help for the word that is clicked on.
:map <2-LeftMouse> :exe "tag " .. expand("<cword>")<CR>
Dragging the mouse with a double click (button-down, button-up, button-down
and then drag) will result in whole words to be selected. This continues
until the button is released, at which point the selection is per character
again.
CTRL-O
in Insert mode. Select mode is used when the
'selectmode' option contains "mouse".
X1Mouse
X1Drag
X1Release
X2Mouse
X2Drag
X2Release
<MiddleRelease>
<MiddleDrag>
Mouse clicks can be mapped. The codes for mouse clicks are:code mouse button normal action --------------------------------------------------------------------------- <LeftMouse> left pressed set cursor position <LeftDrag> left moved while pressed extend selection <LeftRelease> left released set selection end <MiddleMouse> middle pressed paste text at cursor position <MiddleDrag> middle moved while pressed - <MiddleRelease> middle released - <RightMouse> right pressed extend selection <RightDrag> right moved while pressed extend selection <RightRelease> right released set selection end <X1Mouse> X1 button pressed - <X1Drag> X1 moved while pressed - <X1Release> X1 button release - <X2Mouse> X2 button pressed - <X2Drag> X2 moved while pressed - <X2Release> X2 button release -The X1 and X2 buttons refer to the extra buttons found on some mice. The 'Microsoft Explorer' mouse has these buttons available to the right thumb. Currently X1 and X2 only work on Win32 and X11 environments.
:noremap <MiddleMouse> <LeftMouse><MiddleMouse>
Paste at the position of the middle mouse button click (otherwise the paste
would be done at the cursor position).:noremap <LeftRelease> <LeftRelease>y
Immediately yank the selection, when using Visual mode.
:map <X1Mouse> <C-O>
:map <X2Mouse> <C-I>
Map the X1 and X2 buttons to go forwards and backwards in the jump list, see
CTRL-O and CTRL-I.
mouse-swap-buttons
:noremap <LeftMouse> <RightMouse>
:noremap <LeftDrag> <RightDrag>
:noremap <LeftRelease> <RightRelease>
:noremap <RightMouse> <LeftMouse>
:noremap <RightDrag> <LeftDrag>
:noremap <RightRelease> <LeftRelease>
:noremap g<LeftMouse> <C-RightMouse>
:noremap g<RightMouse> <C-LeftMouse>
:noremap! <LeftMouse> <RightMouse>
:noremap! <LeftDrag> <RightDrag>
:noremap! <LeftRelease> <RightRelease>
:noremap! <RightMouse> <LeftMouse>
:noremap! <RightDrag> <LeftDrag>
:noremap! <RightRelease> <LeftRelease>