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 assocciated 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" or "solid".

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).

Examples

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

ns_id

Type: number or string

Namespace id (number) or name (string).

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.

Examples

size = 50,

size = "50%",

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

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

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

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

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

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

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:

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

Examples

popup.border:set_highlight("SpecialChar")

popup.border:set_text

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

Sets border text.

Parameters

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.