spacevim/bundle/nui.nvim/lua/nui/tree

NuiTree

NuiTree can render tree-like structured content on the buffer.

Examples

local NuiTree = require("nui.tree")

local tree = NuiTree({
  bufnr = bufnr,
  nodes = {
    NuiTree.Node({ text = "a" }),
    NuiTree.Node({ text = "b" }, {
      NuiTree.Node({ text = "b-1" }),
      NuiTree.Node({ text = { "b-2", "b-3" } }),
    }),
  },
})

tree:render()

Options

bufnr

Type: number

Id of the buffer where the tree will be rendered.

---

ns_id

Type: number or string

Namespace id (number) or name (string).

---

nodes

Type: table

List of NuiTree.Node objects.

---

get_node_id

Type: function

Signature: get_node_id(node) -> string

If provided, this function is used for generating node's id.

The return value should be a unique string.

Example

get_node_id = function(node)
  if node.id then
    return "-" .. node.id
  end

  if node.text then
    return string.format("%s-%s-%s", node:get_parent_id() or "", node:get_depth(), node.text)
  end

  return "-" .. math.random()
end,

---

prepare_node

Type: function

Signature: prepare_node(node, parent_node?) -> nil | string | string[] | NuiLine | NuiLine[]

If provided, this function is used for preparing each node line.

The return value should be a NuiLine object or string or a list containing either of them.

If return value is nil, that node will not be rendered.

Example

prepare_node = function(node)
  local line = NuiLine()

  line:append(string.rep("  ", node:get_depth() - 1))

  if node:has_children() then
    line:append(node:is_expanded() and " " or " ")
  else
    line:append("  ")
  end

  line:append(node.text)

  return line
end,

---

buf_options

Type: table

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

Examples

buf_options = {
  bufhidden = "hide",
  buflisted = false,
  buftype = "nofile",
  swapfile = false,
},

Methods

tree:get_node

Signature: tree:get_node(node_id_or_linenr?) -> NuiTreeNode | nil, number | nil, number | nil

Parameters

Name	Type	Description
node_id_or_linenr	number or string or nil	node's id or line number

If node_id_or_linenr is string, the node with that id is returned.

If node_id_or_linenr is number, the node on that linenr is returned.

If node_id is nil, the current node under cursor is returned.

Returns the node if found, and the start and end linenr if it is rendered.

tree:get_nodes

Signature: tree:get_node(parent_id?) -> NuiTreeNode[]

Parameters

Name	Type	Description
parent_id	string or nil	parent node's id

If parent_id is present, child nodes under that parent are returned, Otherwise root nodes are returned.

tree:add_node

Signature: tree:add_node(node, parent_id?)

Adds a node to the tree.

Name	Type	Description
node	NuiTree.Node	node
parent_id	string or nil	parent node's id

If parent_id is present, node is added under that parent, Otherwise node is added to the tree root.

tree:remove_node

Signature: tree:remove_node(node)

Removes a node from the tree.

Returns the removed node.

Name	Type	Description
node_id	string	node's id

tree:set_nodes

Signature: tree:set_nodes(nodes, parent_id?)

Adds a node to the tree.

Name	Type	Description
nodes	NuiTree.Node[]	list of nodes
parent_id	string or nil	parent node's id

If parent_id is present, nodes are set as parent node's children, otherwise nodes are set at tree root.

tree:render

Signature: tree:render(linenr_start?)

Renders the tree on buffer.

Name	Type	Description
linenr_start	number / nil	start line number (1-indexed)

NuiTree.Node

NuiTree.Node is used to create a node object for NuiTree.

Signature: NuiTree.Node(data, children)

Examples

local NuiTree = require("nui.tree")

local node = NuiTree.Node({ text = "b" }, {
  NuiTree.Node({ text = "b-1" }),
  NuiTree.Node({ text = "b-2" }),
})

Parameters

data

Type: table

Data for the node. Can contain anything. The default get_node_id and prepare_node functions uses the id and text keys.

Example

{
  id = "/usr/local/bin/lua",
  text = "lua"
}

If you don't want to provide those two values, you should consider providing your own get_node_id and prepare_node functions.

children

Type: table

List of NuiTree.Node objects.

Methods

node:get_id

Signature: node:get_id()

Returns node's id.

node:get_depth

Signature: node:get_depth()

Returns node's depth.

node:get_parent_id

Signature: node:get_parent_id()

Returns parent node's id.

node:has_children

Signature: node:has_children()

Checks if node has children.

node:get_child_ids

Signature: node:get_child_ids() -> string[]

Returns ids of child nodes.

node:is_expanded

Signature: node:is_expanded()

Checks if node is expanded.

node:expand

Signature: node:expand()

Expands node.

node:collapse

Signature: node:collapse()

Collapses node.

Wiki Page

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