Skip to main content
  1. Posts/

Using Virtual Text in Neovim

··523 words·3 mins·
Table of Contents

In Neovim, we can use the virtual text feature to place virtual text anywhere in the current buffer, which is not possible with normal text.

A bit of history

Initially, the Nvim core dev bfredl introduced nvim_buf_set_virtual_text() to add virtual text to a buffer in this PR.

Over the time, the code is refactored and deprecated, in favor of the new API function nvim_buf_set_extmark()1.

Plugins utilizing virtual text

Plugins have been using virtual text feature to do various things. Here is a non-exhaustive list:

Using extmarks

The nvim_buf_set_extmark() function has a lot of parameters, and some of them can be confusing for users due to the conciseness of its documentation.

Here is a working example to demonstrate its usage:

local api = vim.api

local bnr = vim.fn.bufnr('%')
local ns_id = api.nvim_create_namespace('demo')

local line_num = 5
local col_num = 5

local opts = {
  end_line = 10,
  id = 1,
  virt_text = {{"demo", "IncSearch"}},
  virt_text_pos = 'overlay',
  -- virt_text_win_col = 20,

local mark_id = api.nvim_buf_set_extmark(bnr, ns_id, line_num, col_num, opts)

In the above, line_num specifies which line we want to put the virtual text. col_num specifies which column we want to put virtual text (but this is actually only half true, since we can put virtual text at any position). col_num shouldn’t exceed the actual column number of the line indicated by line_num. Otherwise, we get the following error message:

E5113: Error while calling lua chunk: test.lua:17: col value outside range

In the opts parameter, there are more options to change the behavior of this function. virt_text is a table of table, where each sub-table contains some text and the highlight group for it.

The option virt_text_pos has three possible values:

  • overlay: overlay the virtual text on the column specified with col_num, this is actually the only case where col_num really works.
  • eol: virtual text is placed at the end of the line (col_num does not take effect).
  • right_align: virtual text is placed on the right of current line (col_num does not take effect).

Check the title image for a comparison between the three position method.

To actually put virtual text on any column, we should use virt_text_win_col in the opts table. If we use virt_text_win_col, virt_text_pos does not take effect any more.

To delete a virtual text, use API function nvim_buf_del_extmark(bnr, ns_id, id), where id is the id used in opts.


  1. In fact, extmark is more than virtual text, see :h api-extended-marks for the details. ↩︎

  2. As of writing of this post, this plugin is still using the old API. ↩︎


Migrating from Packer.nvim to Lazy.nvim
··651 words·4 mins
Pylsp setup for Neovim in 2023
··1020 words·5 mins
Work with JSON File in Neovim
·299 words·2 mins