SpaceVim/bundle/nui.nvim/lua/nui/layout/README.md

Layout

Layout is a helper component for creating complex layout by automatically handling the calculation for position and size of other components.

Example

local Layout = require("nui.layout")
local Popup = require("nui.popup")

local top_popup = Popup({ border = "single" })
local bottom_popup = Popup({ border = "double" })

local layout = Layout(
  {
    position = "50%",
    size = {
      width = 80,
      height = 40,
    },
  },
  Layout.Box({
    Layout.Box(top_popup, { size = "40%" }),
    Layout.Box(bottom_popup, { size = "60%" }),
  }, { dir = "col" })
)

layout:mount()

Signature: Layout(options, box) or Layout(component, box)

component can be Popup or Split.

Options

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

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%",
},

Layout.Box

Signature: Layout.Box(box, options)

Parameters

Name	Type	Description
box	Layout.Box[] / nui component	list of Layout.Box or any nui component
options	table	box options

options is a table having the following keys:

Key	Type	Description
dir	"col" / "row" (default)	arrangement direction, only if box is Layout.Box[]
grow	number	growth factor to fill up the box free space
size	number / string / table	optional if grow is present

Methods

layout:mount

Signature: layout:mount()

Mounts the layout with all the components.

Examples

layout:mount()

layout:unmount

Signature: layout:unmount()

Unmounts the layout with all the components.

Examples

layout:unmount()

layout:hide

Signature: layout:hide()

Hides the layout with all the components. Preserves the buffer (related content, autocmds and keymaps).

layout:show

Signature: layout:show()

Shows the hidden layout with all the components.

layout:update

Signature: layout:update(config, box?) or layout:update(box?)

Parameters

config is a table having the following keys:

Key	Type
relative	string / table
position	string / table
size	string / table

box is a table returned by Layout.Box.

They are the same options used for layout initialization.

Wiki Page

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