layout

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 = "double" })
local bottom_left_popup = Popup({ border = "single" })
local bottom_right_popup = Popup({ border = "single" })

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

layout:mount()

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

component can be Popup or Split.

Options (for float layout)

anchor

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

Decides which corner of the layout 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 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.

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

Options (for split layout)

relative

Type: string or table

This option affects how size is calculated.

Examples

Split current editor screen:

relative = "editor"

Split current window (default):

relative = "win"

Split window with specific id:

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

---

position

Type: "top" | "right"| "bottom" | "left".

---

size

Type: number or percentage string

Determines the size of the layout.

For percentage string, size is calculated according to the option relative.

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
anchor	"NW" / "NE" / "SW" / "SE"
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.