Layout

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

Example

lua

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:

lua

relative = "cursor",

Relative to the current editor screen:

lua

relative = "editor",

Relative to the current window (default):

lua

relative = "win",

Relative to the window with specific id:

lua

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

Relative to the buffer position:

lua

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

lua

position = 50,

lua

position = "50%",

lua

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

lua

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

lua

size = 50,

lua

size = "50%",

lua

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

lua

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

lua

layout:mount()

`layout:unmount`

Signature: layout:unmount()

Unmounts the layout with all the components.

Examples

lua

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.