Overview

NvChad's Ui plugin handles the following modules:

  • Statusline
  • Tabufline ( bufferline + tablist )
  • NvDash ( Minimal dashboard )
  • Term ( terminal handling )

Tabufline and Statusline

  • Both of the plugins share the same way to customize their appearance.
  • The order is a list of module names from default modules + your modules
  • Removing a word in the order will remove that module
  • Modules expect all its keys to be a function that returns a string.
  • Statusline modules can also have strings!
  • To highlight a string in statusline/tabufline, wrap it with your highlight group, or the existing ones from the theme.
M.ui = {
  tabufline = {
    --  more opts
    order = { "treeOffset", "buffers", "tabs", "btns", 'abc' },
    modules = {
      -- You can add your custom component
      abc = function()
        return "hi"
      end,
    }
  },

  statusline = {
    -- more opts
    order = {...}, -- check stl/utils.lua file in ui repo 
    modules = {
      -- The default cursor module is override
      cursor = function()
        return "%#BruhHl#" .. " bruh " -- the highlight group here is BruhHl,
      end
    }
  }
}

  • For more customization, you should read carefully the default default sets of options in the nvconfig.lua, then check the source code of their module order tables at ui repo.

Term

  • The term module exposes the following functions which expect a table of :
{
  pos = "sp", -- sp/vsp/float
  cmd* = "neofetch" -- any command (supports function too)
  size = 0.5 -- will work for split windows only

  -- this will highlight the term window differently
  hl* = "Normal:term,WinSeparator:WinSeparator",

  id =  "any string" -- needed for toggle/runner func
  float_opts* = {} -- floating window options
  clear_cmd = true -- needed for runner func*
}

  • *ones are optional
  • pos is required.
  • id is needed for toggleable/runner terminals only
  • If the optional opts are not provided then they will be taken from the ui.term table of your chadrc.

New Window

  • Create new terminal windows
require("nvchad.term").new { pos = "sp", size = 0.3 }
require("nvchad.term").new { pos = "vsp", cmd = "neofetch"}

Toggleable

  • Create toggleable terminal windows
require("nvchad.term").toggle({ pos = "float", id = "floatTerm", float_opts = {
      border = "double",
  }})

require("nvchad.term").toggle { pos = "float", id = "floa", cmd ='lazygit' }
require("nvchad.term").toggle { pos = "sp", id = "xyz" }
require("nvchad.term").toggle { pos = "sp", id = "xyz2" }
require("nvchad.term").toggle { pos = "vsp", id = "floo" }

  • Mapping example
  • We are mapping in "t" terminal mode too or else we'd have to go to normal mode and press <A-i> to toggle terminal.
local map = vim.keymap.set

map({ "n", "t" }, "<A-i>", function()
  require("nvchad.term").toggle { pos = "float", id = "floatTerm" }
end, { desc = "Terminal Toggle Floating term" })

Runner

  • This function will first open a terminal + runs the cmd
  • Calling the function again will run the cmd in that terminal window
  • This can be seen as a code runner too! Usually useful if you want to see the result of some command
require("nvchad.term").runner {
    pos = "vsp",
    cmd = "python test.py",
    id = "ekk",
    clear_cmd = false
  }

  • As Cmd can be a function too, here's a complex example :
require("nvchad.term").runner {
  id = "boo",
  pos = "sp",

  cmd = function()
    local file = vim.fn.expand "%"

    local ft_cmds = {
      python = "python3 " .. file,
      cpp = "clear && g++ -o out " .. file .. " && ./out",
    }

    return ft_cmds[vim.bo.ft]
  end,
}

Telescope extensions

These are few telescope extensions present in the UI plugin.

Theme picker

  • This will show a list of themes from base46 and live-preview them + pressing enter will save them in chadrc.
  • Command Telescope themes

Hidden Term picker

  • If you close any terminal window by our close_buffer func i.e <leader>x then it'll just hide it
  • You can un-hide them back by using <leader>pt keymap + press enter
  • Command Telescope terms