Renderer

Renderer is a key element in building UI with NuiComponents. Renderer takes responsibility for rendering, layout, focus management, and keybindings for the components it contains. Developers can create complex interfaces by nesting components within each other, and can also reuse them with different configurations.

Usage Example

local renderer = n.create_renderer({
  width = 80,
  height = 40,
})
 
local signal = n.create_signal(…)
 
local subscription = signal:observe(function(previous_state, current_state)
  -- call side effects
end)
 
local body = function()
  return n.rows(…)
end
 
renderer:add_mappings({
  {
    mode = { "n", "i" },
    from = "<leader>c",
    to = function()
      renderer:close()
    end,
  },
})
 
renderer:on_unmount(function()
  subscription:unsubscribe()
end)
 
renderer:render(body)

Properties

width

Refers to the number of characters that can be displayed horizontally by the renderer.

height

Refers to the number of lines that can be displayed vertically by the renderer.

position

Sets the window position.

relative

Sets the window layout to "floating" (NuiComponents doesn't support split layouts at the moment).

keymap

A table containing a default global key bindings for the renderer.

{
  close = "<Esc>",
  focus_next = "<Tab>",
  focus_prev = "<S-Tab>",
  focus_left = nil,
  focus_right = nil,
  focus_up = nil,
  focus_down = nil
}

on_mount

Registers a callback that will be executed when the component tree is mounted for the first time.

on_unmount

Registers a callback function to be executed when the component tree is unmounted (i.e., the window is closed).

Methods

render

Renders the component tree.

Examples:

local n = require("nui-components")
 
local renderer = n.create_renderer({
  width = 100,
  height = 24,
})
 
local body = function()
  return n.rows(…)
end
 
vim.keymap.set("n", "<leader>i", function()
  renderer:render(body)
end, { noremap = true, desc = "" })

local n = require("nui-components")
 
local renderer = n.create_renderer({
  width = 100,
  height = 24,
})
 
vim.keymap.set("n", "<leader>i", function()
  local body = n.rows(…)
  renderer:render(body)
end, { noremap = true, desc = "" })

schedule

Schedules a callback to be executed after the current update cycle has finished.

redraw

Forces an immediate redraw of the component tree.

focus

Sets the focus to the current renderer window.

close

Closes the current renderer window.

add_mappings

Adds additional keyboard shortcuts for the component tree.

{
  mode = string[] | string, -- "n", "i", "v"
  key = string,
  handler = function
}

set_size

Changes the size of the renderer window.

{
  width = number,
  height = number
}

get_size

Returns the current size of the renderer window.

get_component_by_id

Searches the component tree for a component with the specified id and returns it if found.

get_component_by_direction

Searches the component tree for a focusable component in the specified direction, starting from the focused component, or the specified from component if provided.

get_origin_winid

Returns the original window id when the component tree was first rendered.

get_last_focused_component

Returns the last focused component within the component tree.

get_focusable_components

Returns a list of all focusable components within the tree.

get_component_tree

Returns the entire internal tree used by the component

on_mount

Registers a callback function to be executed when the component tree is first mounted.

on_unmount

Registers a function to be called when the component tree is unmounted.