input

Input

Input is an abstraction layer on top of Popup.

It uses prompt buffer (check :h prompt-buffer) for its popup window.

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

local popup_options = {
  relative = "cursor",
  position = {
    row = 1,
    col = 0,
  },
  size = 20,
  border = {
    style = "rounded",
    text = {
      top = "[Input]",
      top_align = "left",
    },
  },
  win_options = {
    winhighlight = "Normal:Normal",
  },
}

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,
})

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:

-- unmount input by pressing `<Esc>` in normal mode
input:map("n", "<Esc>", function()
  input:unmount()
end, { noremap = true })

You can manipulate the associated buffer and window using the input.bufnr and input.winid properties.

NOTE: the first argument accepts options for nui.popup component.

Options

prompt

Type: string or NuiText

Prefix in the input.

default_value

Type: string

Default value placed in the input on mount

on_close

Type: function

Signature: on_close() -> nil

Callback function, called when input is closed.

on_submit

Type: function

Signature: on_submit(value: string) -> nil

Callback function, called when input value is submitted.

on_change

Type: function

Signature: on_change(value: string) -> nil

Callback function, called when input value is changed.

disable_cursor_position_patch

By default, nui.input will try to make sure the cursor on parent window is not moved after input is submitted/closed. If you want to disable this behavior for some reason, you can set disable_cursor_position_patch to true.

Methods

Methods from nui.popup are also available for nui.input.

Wiki Page

You can find additional documentation/examples/guides/tips-n-tricks in nui.input wiki page.