dotfiles/.config/nvim/pack/tree/start/nui.nvim/lua/nui/popup

Popup

Popup is an abstraction layer on top of window.

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

Examples

local Popup = require("nui.popup")

local popup = Popup({
  position = "50%",
  size = {
    width = 80,
    height = 40,
  },
  enter = true,
  focusable = true,
  zindex = 50,
  relative = "editor",
  border = {
    padding = {
      top = 2,
      bottom = 2,
      left = 3,
      right = 3,
    },
    style = "rounded",
    text = {
      top = " I am top title ",
      top_align = "center",
      bottom = "I am bottom title",
      bottom_align = "left",
    },
  },
  buf_options = {
    modifiable = true,
    readonly = false,
  },
  win_options = {
    winblend = 10,
    winhighlight = "Normal:Normal,FloatBorder:FloatBorder",
  },
})

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

Options

border

Type: table

Contains all border related options.

border.padding

Type: table

Controls the popup padding.

Examples

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

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

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

border = {
  -- `1` for top, `2` for left, `0` for other sides
  padding = {
    top = 1,
    left = 2,
  },
},

border.style

Type: string or table

Controls the styling of the border.

Examples

Can be one of the pre-defined styles: "double", "none", "rounded", "shadow", "single", "solid" or "default".

border = {
  style = "double",
},

List (table) of characters starting from the top-left corner and then clockwise:

border = {
  style = { "╭", "─", "╮", "│", "╯", "─", "╰", "│" },
},

Map (table) with named characters:

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

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

To set the highlight group for all the border characters, use the win_options.winhighlight option and include the name of highlight group for FloatBorder.

Examples

win_options = {
  winhighlight = "Normal:Normal,FloatBorder:SpecialChar",
},

To set the highlight group for individual border character, you can use NuiText or a tuple with (char, hl_group).

Examples

border = {
  style = { { [[/]], "SpecialChar" }, [[─]], NuiText([[\]], "SpecialChar"), [[│]] },
},

border.text

Type: table

Text displayed on the border (as title/footnote).

Key	Type	Description
"top"	string / NuiLine / NuiText	top border text
"top_align"	"left" / "right"/ "center" (default)	top border text alignment
"bottom"	string / NuiLine / NuiText	bottom border text
"bottom_align"	"left" / "right"/ "center" (default)	bottom border text alignment

"top" and "bottom" also supports list of (text, hl_group) tuples, just like the native popup.

Examples

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

---

ns_id

Type: number or string

Namespace id (number) or name (string).

---

anchor

Type: "NW" / "NE" / "SW" / "SE"

Decides which corner of the popup to place at position.

---

relative

Type: string or table

This option affects how position and size are calculated.

Examples

Relative to cursor on current window:

relative = "cursor",

Relative to the current editor screen:

relative = "editor",

Relative to the current window (default):

relative = "win",

Relative to the window with specific id:

relative = {
  type = "win",
  winid = 5,
},

Relative to the buffer position:

relative = {
  type = "buf",
  -- zero-indexed
  position = {
    row = 5,
    col = 5,
  },
},

---

position

Type: number or percentage string or table

Position is calculated from the top-left corner.

If position is number or percentage string, it applies to both row and col. Or you can pass a table to set them separately.

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

Examples

position = 50,

position = "50%",

position = {
  row = 30,
  col = 20,
},

position = {
  row = "20%",
  col = "50%",
},

---

size

Type: number or percentage string or table

Determines the size of the popup.

If size is number or percentage string, it applies to both width and height. You can also 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.

Decimal number in (0,1) range is treated similar to percentage string. For example: 0.5 is same as "50%".

Examples

size = 50,

size = "50%",

size = 0.5,

size = {
  width = 80,
  height = 40,
},

size = {
  width = "80%",
  height = 0.6,
},

---

enter

Type: boolean

If true, the popup is entered immediately after mount.

Examples

enter = true,

---

focusable

Type: boolean

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

Examples

focusable = true,

---

zindex

Type: number

Sets the order of the popup on z-axis.

Popup with higher the zindex goes on top of popups with lower zindex.

Examples

zindex = 50,

---

buf_options

Type: table

Contains all buffer related options (check :h options | /local to buffer).

Examples

buf_options = {
  modifiable = false,
  readonly = true,
},

---

win_options

Type: table

Contains all window related options (check :h options | /local to window).

Examples

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

---

bufnr

Type: number

You can pass bufnr of an existing buffer to display it on the popup.

Examples:

bufnr = vim.api.nvim_get_current_buf(),

Methods

popup:mount

Signature: popup:mount()

Mounts the popup.

Examples

popup:mount()

---

popup:unmount

Signature: popup:unmount()

Unmounts the popup.

Examples

popup:unmount()

---

popup:hide

Signature: popup:hide()

Hides the popup window. Preserves the buffer (related content, autocmds and keymaps).

---

popup:show

Signature: popup:show()

Shows the hidden popup window.

---

popup:map

Signature: popup:map(mode, key, handler, opts) -> nil

Sets keymap for the popup.

Parameters

Name	Type	Description
mode	string	check :h :map-modes
key	string	key for the mapping
handler	string / function	handler for the mapping
opts	table	check :h :map-arguments (including remap/noremap, excluding buffer)

Examples

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

---

popup:unmap

Signature: popup:unmap(mode, key) -> nil

Deletes keymap for the popup.

Parameters

Name	Type	Description
mode	"n" / "i"	check :h :map-modes
key	string	key for the mapping

Examples

local ok = popup:unmap("n", "<esc>")

---

popup:on

Signature: popup:on(event, handler, options)

Defines autocmd to run on specific events for this popup.

Parameters

Name	Type	Description
event	string[] / string	check :h events
handler	function	handler function for event
options	table	keys once, nested and values boolean

Examples

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

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

event can be expressed as any of the followings:

{ event.BufLeave, event.BufDelete }
-- or
{ event.BufLeave, "BufDelete" }
-- or
event.BufLeave
-- or
"BufLeave"
-- or
"BufLeave,BufDelete"

---

popup:off

Signature: popup:off(event)

Removes autocmd defined with popup:on({ ... })

Parameters

Name	Type	Description
event	string[] / string	check :h events

Examples

popup:off("*")

---

popup:update_layout

Signature: popup:update_layout(config)

Sets the layout of the popup. You can use this method to change popup's size or position after it's mounted.

Parameters

config is a table having the following keys:

Key	Type
anchor	"NW" / "NE" / "SW" / "SE"
relative	string / table
position	string / table
size	string / table

They are the same options used for popup initialization.

Examples

popup:update_layout({
  relative = "win",
  size = {
    width = 80,
    height = 40,
  },
  position = {
    row = 30,
    col = 20,
  },
})

---

popup.border:set_highlight

Signature: popup.border:set_highlight(highlight: string) -> nil

Sets border highlight.

Parameters

Name	Type	Description
highlight	string	highlight group name

Examples

popup.border:set_highlight("SpecialChar")

---

popup.border:set_style

Signature: popup.border:set_style(style: string|table) -> nil

Sets border style.

Parameters

Name	Type	Description
style	string / table	border style

This style parameter is exactly the same as popup option border.style.

You'll need to call popup:update_layout() after this for the change to render on screen.

Examples

popup.border:set_style("rounded")
popup:update_layout()

---

popup.border:set_text

Signature: popup.border:set_text(edge, text, align)

Sets border text.

Parameters

Name	Type
edge	"top" / "bottom" / "left" / "right"
text	string
align	"left" / "right"/ "center"

Examples

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

Wiki Page

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