Nvim:help pages,generated fromsource using thetree-sitter-vimdoc parser.
options parameter is a mapwith these (optional) keys:rgb Decides the color format.override Decides how UI capabilities are resolved.ext_cmdline Externalize the cmdline.ui-cmdlineext_tabline Externalize the tabline.ui-tablineext_termcolors Use external default colors.term_name Sets the name of the terminal'term'.term_colors Sets the number of supported colors 't_Co'.stdin_fd Read buffer 1 from this fd as if it were stdin--.Only from--embed UI on startup.ui-startup-stdinstdin_tty Tells ifstdin is atty or not.stdout_tty Tells ifstdout is atty or not.ui_options key for supported options.['notification', 'redraw', [ ['grid_resize', [2, 77, 36]], ['grid_line', [2, 0, 0, [[' ' , 0, 77]], false], [2, 1, 0, [['~', 7], [' ', 7, 76]], false], [2, 9, 0, [['~', 7], [' ', 7, 76]], false], ... [2, 35, 0, [['~', 7], [' ', 7, 76]], false], [1, 36, 0, [['[', 9], ['N'], ['o'], [' '], ['N'], ['a'], ['m'], ['e'], [']']], false], [1, 36, 9, [[' ', 9, 50]], false], [1, 36, 59, [['0', 9], [','], ['0'], ['-' ], ['1'], [' ', 9, 10], ['A'], ['l', 9, 2]], false] ], ['msg_showmode', [[]]], ['win_pos', [2, 1000, 0, 0, 77, 36]], ['grid_cursor_goto', [2, 0, 0]], ['flush', []] ]]Events must be handled in-order. Nvim sends a "flush" event when it hascompleted a redraw of the entire screen (so all windows have a consistent viewof buffer state, options, etc.). Multiple "redraw" batches may be sent beforethe entire screen has been redrawn, with "flush" following only the lastbatch. The user should only see the final state (when "flush" is sent), notany intermediate state while processing part of the batch array, nor aftera batch not ending with "flush".
nvim --embednvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")stdin_fd parameter ofnvim_ui_attach. Nvim will read it as text into buffer 1.cursor_style_enabled is a boolean indicating if the UI should setthe cursor style.mode_info is a list of mode property maps. Thecurrent mode is given by themode_idx field of themode_changeevent.cursor_shape:"block", "horizontal", "vertical"cell_percentage: Cell % occupied by the cursor.blinkwait,blinkon,blinkoff: Seecursor-blinking.attr_id:Cursor attribute id (defined byhl_attr_define).When attr_id is 0, the background and foregroundcolors should be swapped.attr_id_lm:Cursor attribute id for when:lmap is on.short_name:Mode code name, see'guicursor'.name:Mode descriptive name.mouse_shape:(To be implemented.)hl_id:Useattr_id instead.id_lm:Useattr_id_lm instead.name is one of:mode parameter is a string representingthe current mode.mode_idx is an index into the array emitted inthemode_info_set event. UIs should change the cursor styleaccording to the properties specified in the corresponding item. Theset of modes reported will change in new versions of Nvim, forinstance more submodes and temporary states might be represented asseparate modes.progpath as the full path to the Nvim executablev:progpath andargv as its argumentsv:argv, and reattach to the new server.Note:--embed and--headless are excluded fromargv, and the clientshould decide itself whether to add either flag.{content} to the connected TTY. Only UIs that have the"stdout_tty"ui-option set will receive this event.ext_linegridui-option. Recommended for all new UIs.Deactivatesui-grid-old implicitly.grid_line event toupdate a screen-line (whereas the old protocol emitted separate cursor,highlight and text events per screen-line).grid index as first parameter. Grid 1 is theglobal grid used by default for the entire editor screen state. Theext_linegrid capability by itself will never cause any additional grids tobe created; to enable per-window grids, activateui-multigrid.grid. Ifgrid wasn't seen by the client before, a new grid isbeing created with this size.cterm_fg andcterm_bg specifies thedefault color codes to use in a 256-color terminal.ext_termcolors option, instead-1 will be used for unset colors. This is mostly useful for a TUIimplementation, where using the terminal builtin ("ANSI") defaultsare expected.id to the highlight table, with theattributes specified by thergb_attr andcterm_attr dicts, with thefollowing (all optional) keys.foreground:foreground color.background:background color.special:color to use for various underlines, whenpresent.reverse:reverse video. Foreground and background colorsare switched.italic:italic text.bold:bold text.strikethrough:struckthrough text.underline:underlined text. The line hasspecial color.undercurl:undercurled text. The curl hasspecial color.underdouble:double underlined text. The lines havespecial color.underdotted:underdotted text. The dots havespecial color.underdashed:underdashed text. The dashes havespecial color.altfont:alternative font.blend:blend level (0-100). Could be used by UIs tosupport blending floating windows to thebackground or to signal a transparent cursor.url:URL associated with this highlight. UIs shouldpresent the region as a clickable hyperlink.rgb_attr andcterm_attr parametersrespectively. Theui-rgb option has no effect anymore.Most external UIs will only need to store and use thergb_attrattributes.id 0 will always be used for the default highlight with colors definedbydefault_colors_set and no styles applied.id values if its internal highlight table is full.In that case Nvim will always issue redraws of screen cells that areaffected by redefined ids, so UIs do not need to keep track of thisthemselves.info is an empty array unlessui-hlstate is enabled.name was set to use the attributeshl_iddefined by a previoushl_attr_define call. This event is not neededto render the grids which use attribute ids directly, but is usefulfor a UI who want to render its own elements with consistenthighlighting. For instance a UI usingui-popupmenu events, mightuse thehl-Pmenu family of builtin highlights.row on agrid, starting at the columncol_start.cells is an array of arrays each with 1 to 3 items:[text(, hl_id, repeat)] .text is the UTF-8 text that should be put ina cell, with the highlighthl_id defined by a previoushl_attr_definecall. Ifhl_id is not present the most recently seenhl_id inthe same call should be used (it is always sent for the firstcell in the event). Ifrepeat is present, the cell should berepeatedrepeat times (including the first time), otherwise justonce.repeat.wrap is a boolean indicating that this line wraps to the next row.When redrawing a line which wraps to the next row, Nvim will emit agrid_line event covering the last column of the line withwrap setto true, followed immediately by agrid_line event starting at thefirst column of the next row.grid.grid will not be used anymore and the UI can free any data associatedwith it.grid the current grid androw, col the cursor position on thisgrid. This event will be sent at most once in aredraw batch andindicates the visible cursor position.grid. This is semantically unrelated to editorscrolling, rather this is an optimized way to say "copy these screencells".rows is bigger than 0, move a rectangle in the SR up, this canhappen while scrolling down.+-------------------------+| (clipped above SR) | ^|=========================| dst_top || dst (still in SR) | |+-------------------------+ src_top || src (moved up) and dst | ||-------------------------| dst_bot || src (invalid) | |+=========================+ src_bot
rows is less than zero, move a rectangle in the SR down, this canhappen while scrolling up.+=========================+ src_top| src (invalid) | ||------------------------ | dst_top || src (moved down) and dst| |+-------------------------+ src_bot || dst (still in SR) | ||=========================| dst_bot || (clipped below SR) | v+-------------------------+
cols is always zero in this version of Nvim, and reserved for futureuse.set_scroll_region which was end-inclusive.width andheight cells.attrs is a dict with the keys below. Any absent key is resetto its default value. Color defaults are set by theupdate_fg etcupdates. All boolean keys default to false.foreground:foreground color.background:background color.special:color to use for various underlines, when present.reverse:reverse video. Foreground and background colors areswitched.italic:italic text.bold:bold text.strikethrough: struckthrough text.underline:underlined text. The line hasspecial color.undercurl:undercurled text. The curl hasspecial color.underdouble:double underlined text. The lines havespecial color.underdotted:underdotted text. The dots havespecial color.underdashed:underdashed text. The dashes havespecial color.text is put at the cursor position(and the cursor is advanced), with the highlights as set by thelasthighlight_set update.scroll below.+-------------------------+| (clipped above SR) | ^|=========================| dst_top || dst (still in SR) | |+-------------------------+ src_top || src (moved up) and dst | ||-------------------------| dst_bot || src (cleared) | |+=========================+ src_bot
+=========================+ src_top| src (cleared) | ||------------------------ | dst_top || src (moved down) and dst| |+-------------------------+ src_bot || dst (still in SR) | ||=========================| dst_bot || (clipped below SR) | v+-------------------------+
ext_hlstate is enabled, Nvim will emit detailed highlight state inui-linegrid events. Otherwise (by default) Nvim only describes grid cellsusing the final calculated highlight attributes described atui-event-highlight_set.ext_hlstate provides a semantic description of active highlights for eachgrid cell. Highlights are predefined in a table, seeui-event-hl_attr_defineandui-event-grid_line.info parameter inhl_attr_define contains a semantic description ofthe highlights. Because highlight groups can be combined, this is an arraywhere the highest-priority item is last. Each item is a dict with these keys:kind:always present. One of the following values:"ui": Builtin UI highlight.highlight-groups"syntax": Highlight applied to a buffer by a syntax declaration or other runtime/plugin functionality such asnvim_buf_set_extmark() "terminal": highlight from a process running in aterminal-emulator. Contains no further semantic information.ui_name:Highlight name fromhighlight-groups. Only for "ui" kind.hi_name:Name of the final:highlight group where the usedattributes are defined.id:Unique numeric id representing this item.ui_name andhi_name present. These candiffer, because the builtin group was linked to another group:hi-link , orbecause'winhighlight' was used. UI items will be transmitted, even if thehighlight group is cleared, soui_name can always be used to reliably identifyscreen elements, even if no attributes have been applied.win.anchor_grid at the specified positionanchor_row andanchor_col. For the meaning ofanchor and more details of positioning, seenvim_open_win(). NOTE: you have to manually ensure that the window fits the screen, possibly by further reposition it. Ignorescreen_row andscreen_col in this case.anchor and display the window atscreen_row andscreen_col.mouse_enabled is true if the window can receive mouse events.zindex is the configured zindex, whilecompindex is the exactrendering order of the windows determined by nvim. To render exactlylike the TUI, first render all the non-floating windows, then renderin thecompindex order, overwriting any floating window cells.Finally, blend the floating window cells against the non-floatingbackground. To add more blending, you can group the windows by zindex,and blend between the layers. But note that windows inside the samezindex should still overwrite previous cells inside the same layerwithout blending. This ensures that plugins that render multiplewindows, to add borders for example, work as expected.win. The window should bedisplayed as a separate top-level window in the desktop environment,or something similar.grid. The grid will be displayed atrow onthe default grid (grid=1), covering the full column width.scrolledindicates whether the message area has been scrolled to cover othergrids. It can be useful to draw a separator thenmsgsep. The BuiltinTUI draws a full line filled withsep_char ('fillchars' msgsepfield) andhl-MsgSeparator highlight.zindex andcompindex have the same meaning as forwin_float_pos.Thezindex always has a fixed value of 200 and included forcompleteness.botline is set to one more than the line count of the buffer, ifthere are filler lines past the end.scroll_delta contains how muchthe top line of a window moved sincewin_viewport was last emitted.It is intended to be used to implement smooth scrolling. For thispurpose it only counts "virtual" or "displayed" lines, so foldsonly count as one line. When scrolling more than a full screen it isan approximate value.grid_line, in a batch affects the new viewport,despite the fact thatwin_viewport is received after the updates.Applications implementing, for example, smooth scrolling should takethis into account and keep the grid separated from what's displayed onthe screen and copy it to the viewport destination oncewin_viewportis received.win_viewport event. This happense.g. in the presence of'winbar' and floating window borders.ui_watched attribute.ext_popupmenuui-option.mode_change event, command-line wildmenu may be presented horizontally,while insert-mode completion would show a vertical popupmenu.items is an array of completion itemsto show; each item is an array of the form [word, kind, menu, info] asdefined atcomplete-items, except thatword is replaced byabbrif present.selected is the initially-selected item, a zero-basedindex into the array of items (-1 if no item is selected).row andcol give the anchor position, where the first character of thecompleted word will be. Whenui-multigrid is used,grid is thegrid for the anchor position. Whenext_cmdline is active,grid isset to -1 to indicate the popupmenu should be anchored to the externalcmdline. Thencol will be a byte position in the cmdline text.selected is a zero-basedindex into the array of items from the last popupmenu_show event, or-1 if no item is selected.ext_tablineui-option.curbuf +buffers were added in API7.curtab: Current Tabpagetabs: List of Dicts [{ "tab": Tabpage, "name": String }, ...]curbuf: Current buffer handle.buffers: List of Dicts [{ "buffer": buffer handle, "name": String}, ...]ext_cmdlineui-option.content is the full content that should be displayed in thecmdline, and thepos is the position of the cursor that in thecmdline. The content is divided into chunks with different highlightattributes represented as a dict (seeui-event-highlight_set).firstc andprompt are text, that if non-empty should bedisplayed in front of the command line.firstc always indicatesbuilt-in command lines such as: (ex command) and/? (search),whileprompt is aninput() prompt, highlighted withhl_id.indent tells how many spaces the content should be indented.<c-r>= at the command line prompt. Thelevel field is usedto distinguish different command lines active at the same time. Thefirst invoked command line has level 1, the next recursively-invokedprompt has level 2. A command line invoked from thecmdline-windowhas a higher level than the edited command line.shift is true the text after the cursor should be shifted, otherwiseit should overwrite the char at the cursor.level is the nesting level of the cmdline being hidden.abort is true if the cmdline is hidden after an aborting condition(c_Esc orc_CTRL-C).:function Foo(): echo "foo":lines is a list of lines of highlighted chunks, in the same form asthe "cmdline_show"contents parameter.msg_id.:echo ""), with emptycontent.Should clear messages sharing the'cmdheight'area if it is the only message in a batch."bufwrite":write message"confirm"Message preceding a prompt (:confirm,confirm(),inputlist(),z=, …)"emsg"Error (errors, internal error,:throw, …)"echo":echo message"echomsg":echomsg message"echoerr":echoerr message"completion"ins-completion-menu message"list_cmd"List output for various commands (:ls,:set, …)"lua_error"Error in:lua code"lua_print"print() from:lua code"progress"Progress message emitted bynvim_echo()"rpc_error"Error response fromrpcrequest()"quickfix"Quickfix navigation message"search_cmd"Entered search command"search_count"Search count message ("S" flag of'shortmess')"shell_cmd":!cmd executed command"shell_err":!cmd shell stderr output"shell_out":!cmd shell stdout output"shell_ret":!cmd shell return code"undo":undo and:redo message"verbose"'verbose' message"wildlist"'wildmode' "list" message"wmsg"Warning ("search hit BOTTOM",W10, …) New kinds may be added in the future; clients should treat unknown kinds as the empty kind.[attr_id, text_chunk, hl_id] tuples, building up the message text of chunks of different highlights. No extra spacing should be added between chunks, thetext_chunk by itself contains any necessary whitespace. Messages can contain line breaks "\n".msg_show call, but any other visible message should still remain.content has the sameformat as in "msg_show". This event is sent with emptycontent tohide the last message.content has the same format as in "msg_show".This event is sent with emptycontent to hide the last message.content has the same format as in "msg_show". This event issent with emptycontent to hide the last message.