UI Component Library for Neovim.

• Neovim 0.5.0

Install the plugins with your preferred plugin manager. For example, with vim-plug:

Plug 'MunifTanjim/nui.nvim'

Popup is an abstraction layer on top of window.

Creates a new popup object (but does not mount it immediately).

local Popup = require("nui.popup")

local popup = Popup({
  border = {
    style = "rounded",
    highlight = "FloatBorder",
  },
  position = "50%",
  size = {
    width = "80%",
    height = "60%",
  },
  opacity = 1,
})

border

border accepts a table with these keys: highlight, padding, style, and text.

border.highlight can be a string denoting the highlight group name for the border characters.

border.padding can be a list (table) with number of cells for top, right, bottom and left. It behaves like CSS padding. For example:

-- `1` for top/bottom and `2` for left/right
{ 1, 2 }

You can also use a map (table) to set padding at specific side. For example:

-- `1` for top, `0` for other sides
{ top = 1 }

border.style can be one of the followings:

• Pre-defined style: "double", "none", "rounded", "shadow", "single" or "solid"
• List (table) of characters starting from the top-left corner and then clockwise. For example:

  { "╭", "─", "╮", "│", "╯", "─", "╰", "│" }

• Map (table) with named characters. For example:

  {
    top_left    = "╭", top    = "─", top_right     = "╮",
    left        = "│",               right         = "│"
    bottom_left = "╰", bottom = "─", bottom_right  = "╯",
  }

border.text can be an table with the following keys:

Possible values for "top_align" and "bottom_align" are: "left", "right" or "center" (default).

For example:

{
  top = "Popup Title",
  top_align = "center",
}

If you don't need all these options, you can also pass the value of border.style to border directly.

relative

This option affects how position and size is calculated.

Here <Position> is a table with keys row, col and values are zero-indexed numbers.

position

If position is number or percentage string, it applies to both row and col. Or you can pass a table to set them separately. Position is calculated from the top-left corner.

For percentage string, position is calculated according to the option relative (if relative is set to "buf" or "cursor", percentage string is not allowed).

size

If size is number or percentage string, it applies to both width and height. Or you can pass a table to set them separately.

For percentage string, size is calculated according to the option relative (if relative is set to "buf" or "cursor", window size is considered).

enter

If enter is true, the popup is entered immediately after mount.

focusable

If focusable is false, the popup can not be entered by user actions (wincmds, mouse events).

zindex

zindex is a number used to order the position of popups on z-axis. Popup with higher zindex goes on top of popups with lower zindex.

buf_options

Table containing buffer options to set for this popup. For example:

{
  modifiable = false,
  readonly = true,
}

win_options

Table containing window options to set for this popup. For example:

{
  winblend = 10,
  winhighlight = "Normal:Normal",
}

Mounts the popup.

popup:mount()

Unmounts the popup.

popup:unmount()

Sets keymap for this popup. If keymap was already set and force is not true returns false, otherwise returns true.

For example:

local ok = popup:map("n", "<esc>", function(bufnr)
  print("ESC pressed in Normal mode!")
end, { noremap = true })

Defines autocmd to run on specific events for this popup. For example:

local event = require("nui.utils.autocmd").event

popup:on({ event.BufLeave }, function()
  popup:unmount()
end, { once = true })

Removes autocmd defined with popup:on(...). For example:

popup:off("*")

Sets the size of the popup. For example:

popup:set_size({ width = 80, height = 40 })

Sets border text. For example:

popup.border:set_text("bottom", "[Progress: 42%]", "right")

Input is an abstraction layer on top of Popup.

Creates a new input object (but does not mount it immediately).

local Input = require("nui.input")

local input = Input(popup_options, {
  prompt = "> ",
  default_value = "42",
  on_close = function()
    print("Input closed!")
  end,
  on_submit = function(value)
    print("Value submitted: ", value)
  end,
  on_change = function(value)
    print("Value changed: ", value)
  end,
})

All the methods Popup methods is also available for Input. It uses prompt buffer (check :h prompt-buffer) for its popup window.

If you provide the on_change function, it'll be run everytime value changes.

Pressing <CR> runs the on_submit callback function and closes the window. Pressing <C-c> runs the on_close callback function and closes the window.

Of course, you can override the default keymaps and add more. For example:

-- close the input window by pressing `<Esc>` on normal mode
input:map("n", "<Esc>", input.input_props.on_close, { noremap = true })

Licensed under the MIT License. Check the LICENSE file for details.