Customizing Statusline
AstroNvim uses Heirline.nvim for both the custom statusline and winbar. Heirline is an extremely minimal statusline plugin that does not come with any preconfigured elements but focuses on speed and extensibility. To build our statusline, we have built an internal lua module of statusline elements that we use to build our own statusline, but can in turn be used in your user configuration to customize the statusline.
Basic Options
There are some basic options that we have exposed outside of the plugins.heirline table for overriding the Heirline setup(...) function. These options are used to easily change the colors of sections and the separators used for sections. These would be in a top level heirline table in your user/init.lua file or split up into files heirline/separators.lua, heirline/colors.lua, heirline/attributes.lua, and heirline/icon_highlights.lua in your user/ folder.
-
heirline.separatorsprovides an easy way to change the character that surrounds your statusline components. The key is the side of the component and the two characters are the characters to be put on the left and right of the component respectively. -
heirline.colorsprovides an easy way to override the color of each component that we provide in the statusline. We have provided the default options for these which are derived from the current theme that is loaded. The values that we show are the highlight group name and the property that they are using. If you are curious how these values are evaluated, please check out the source code inlus/configs/heirline.lua. Also we set values forgit_branch_fgandtreesitter_fgcorrespond to the names of components inrequire("astronvim.utils.status").component. Any component can be given a color here followed by_fgand_bgto control the foreground and background colors. If a value is not provided then it defaults tosection_fgandsection_bg. We don’t use custom colors for the other sections by default which is why onlygit_branch_fgandtreesitter_fgare set. -
heirline.attributesprovides an easy way to override the highlight attributes for each component that we provide in thestatusAPI. The available options here can be found with:h attr-list. Similar to theheirline.colorstable, we have set the key values corresponding to the names of the components inrequire("astronvim.utils.status").componentAny component can be given attributes. -
heirline.icon_highlightslets you easily control when breadcrumbs and filetype icons should be dynamically or statically colored. By default, LSP breadcrumbs have highlighting disabled and the filetype icon is colored in the statusline, colored for active and visible buffers in the tabline, and disabled in the winbar. These values can either betrueorfalseto enable/disable them always, or a function where the first component is the Heirline component for doing dynamic changing when to color the icon.
Default Options:
heirline = {
separators = {
none = { "", "" },
left = { "", " " },
right = { " ", "" },
center = { " ", " " },
tab = { "", " " },
breadcrumbs = " ",
path = " ",
},
colors = {
fg = StatusLine.fg,
bg = StatusLine.bg,
section_fg = StatusLine.fg,
section_bg = StatusLine.bg,
git_branch_fg = Conditional.fg,
treesitter_fg = String.fg,
scrollbar = TypeDef.fg,
git_added = GitSignsAdd.fg,
git_changed = GitSignsChange.fg,
git_removed = GitSignsDelete.fg,
diag_ERROR = DiagnosticError.fg,
diag_WARN = DiagnosticWarn.fg,
diag_INFO = DiagnosticInfo.fg,
diag_HINT = DiagnosticHint.fg,
winbar_fg = WinBar.fg,
winbar_bg = WinBar.bg,
winbarnc_fg = WinBarNC.fg,
winbarnc_bg = WinBarNC.bg,
tabline_bg = StatusLine.bg,
tabline_fg = StatusLine.bg,
buffer_fg = Comment.fg,
buffer_path_fg = WinBarNC.fg,
buffer_close_fg = Comment.fg,
buffer_bg = StatusLine.bg,
buffer_active_fg = Normal.fg,
buffer_active_path_fg = WinBarNC.fg,
buffer_active_close_fg = Error.fg,
buffer_active_bg = Normal.bg,
buffer_visible_fg = Normal.fg,
buffer_visible_path_fg = WinBarNC.fg,
buffer_visible_close_fg = Error.fg,
buffer_visible_bg = Normal.bg,
buffer_overflow_fg = Comment.fg,
buffer_overflow_bg = StatusLine.bg,
buffer_picker_fg = Error.fg,
tab_close_fg = Error.fg,
tab_close_bg = StatusLine.bg,
tab_fg = TabLine.fg,
tab_bg = TabLine.bg,
tab_active_fg = TabLineSel.fg,
tab_active_bg = TabLineSel.bg,
inactive = HeirlineInactive.fg,
normal = HeirlineNormal.fg,
insert = HeirlineInsert.fg,
visual = HeirlineVisual.fg,
replace = HeirlineReplace.fg,
command = HeirlineCommand.fg,
terminal = HeirlineTerminal.fg,
},
attributes = {
buffer_active = { bold = true, italic = true },
buffer_picker = { bold = true },
macro_recording = { bold = true },
git_branch = { bold = true },
git_diff = { bold = true },
}
icon_highlights = {
breadcrumbs = false,
file_icon = {
tabline = function(self) return self.is_active or self.is_visible end,
statusline = true,
winbar = false,
},
}
}Using astronvim.utils.status Module
AstroNvim provides a module that can be loaded with require("astronvim.utils.status") for building components in Heirline for both the statusline and winbar. It has several submodules:
| Module | Description |
|---|---|
require("astronvim.utils.status") | Easily import all of the below modules |
require("astronvim.utils.status.component") | A collection of methods to assist in building entire components. This is the main piece to interact with when building custom statuslines |
require("astronvim.utils.status.hl") | A collection of methods to assist in setting the color of a component |
require("astronvim.utils.status.provider") | A collection of methods that can be set as Heirline providers |
require("astronvim.utils.status.condition") | A collection of methods that can be use as Heirline conditions for controlling when components are enabled |
require("astronvim.utils.status.init") | A collection of methods that can be set as Heirline init functions for building components with dynamic subcomponents such as LSP breadcrumbs |
require("astronvim.utils.status.utils") | A collection of miscellaneous helper functions that astronvim.utils.status uses such as surrounding components and getting buffers |
require("astronvim.utils.status.env") | A place to store globally accessible variables such as separators, mode text, etc. |
require("astronvim.utils.status.heirline") | A collection of tools specific for Heirline as well as a few aliases for easily interfacing with Heirline utilities |
Heirline is built through building up components in a nested way, where each component either has it’s own sub components or a provider to tell what content should be displayed. For a detailed description on the basic concepts of configuring Heirline, please check out their extremely well written cookbook.
Building a Component From Scratch
To build a component from the ground up, we can first start by selecting a provider from the require("astronvim.utils.status").provider module, for example we can use the require("astronvim.utils.status").provider.mode_text provider to get the text for the current mode (i.e. NORMAL, INSERT, etc.). Each provider takes a single argument table with options. Some providers have their own options, but all have a common set of options for stylizing the string they provide. These options include padding, separator characters, and an icon to be used.
Using these options we can start building our component:
local component = {
provider = require("astronvim.utils.status").provider.mode_text({ padding = { left = 1, right = 1 } }),
}This will give us a component where the text will be the current mode displayed as text. But now we want to be able to have the background of the mode to change colors along with the mode. This is where the require("astronvim.utils.status").hl module comes into play. There is a method there for getting the highlight for a mode with require("astronvim.utils.status").hl.mode. Each of these hl methods are designed to be passed in by name instead of resolving the function to the hl field in a Heirline component. For example, we can add the mode highlighting to our component as such:
local component = {
provider = require("astronvim.utils.status").provider.mode_text({ padding = { left = 1, right = 1 } }),
hl = require("astronvim.utils.status").hl.mode,
}This will give us a simple component where the background changes colors with each mode and displays the text of the current mode. If we want to make this component a bit prettier and add surrounding characters, we can use the require("astronvim.utils.status").utils.surround function with our component to do this. This surround method also handles setting the highlight group so we no longer need to set that inside of our component. An example of this would be:
local component = {
provider = require("astronvim.utils.status").provider.mode_text({ padding = { left = 1, right = 1 } }),
}
local surrounded_component = require("astronvim.utils.status").utils.surround({ "", " "}, require("astronvim.utils.status").hl.mode_bg, component)This function takes three parameters: the first parameter (left and right side respectively), the second parameter is the function for setting the color for the background of the component and the foreground of the separators, and the third parameter is the component that should be surrounded. In turn it gives us our final component that can be used inside of Heirline.
Using the Predefined Components in require("astronvim.utils.status").component
Building components from scratch is a powerful method that gives users complete control, but for the most part it’s nice to have fully built components without having to think as much about what’s going on internally. For this we have created several out of the box component building functions for things such as the mode, file details, git information, etc. With these, it becomes much easier to build components that you would want in your statusline. For example, to recreate our previous mode text component we can do this:
local component = require("astronvim.utils.status").component.mode({
mode_text = { padding = { left = 1, right = 1 } },
})This will automatically set up the surrounding and colors that we want and defaults to it being a left aligned component. If you are going to place the component on the right side and want it to have the right side separators instead, you can do this:
local component = require("astronvim.utils.status").component.mode({
mode_text = { padding = { left = 1, right = 1 } },
surround = { separator = "right" },
})Default Heirline Configuration
This is a code block that redefines the default statusline and winbar that are used in AstroNvim inside of the user configuration file for reference and a starting point to make modifications:
return {
plugins = {
{
"rebelot/heirline.nvim",
opts = function(_, opts)
local status = require("astronvim.utils.status")
opts.statusline = { -- statusline
hl = { fg = "fg", bg = "bg" },
status.component.mode(),
status.component.git_branch(),
status.component.file_info { filetype = {}, filename = false, file_modified = false },
status.component.git_diff(),
status.component.diagnostics(),
status.component.fill(),
status.component.cmd_info(),
status.component.fill(),
status.component.lsp(),
status.component.treesitter(),
status.component.nav(),
status.component.mode { surround = { separator = "right" } },
}
opts.winbar = { -- winbar
init = function(self) self.bufnr = vim.api.nvim_get_current_buf() end,
fallthrough = false,
{ -- inactive winbar
condition = function() return not status.condition.is_active() end,
status.component.separated_path(),
status.component.file_info {
file_icon = { hl = status.hl.file_icon "winbar", padding = { left = 0 } },
file_modified = false,
file_read_only = false,
hl = status.hl.get_attributes("winbarnc", true),
surround = false,
update = "BufEnter",
},
},
{ -- active winbar
status.component.breadcrumbs { hl = status.hl.get_attributes("winbar", true) },
},
},
opts.tabline = { -- tabline
{ -- file tree padding
condition = function(self)
self.winid = vim.api.nvim_tabpage_list_wins(0)[1]
return status.condition.buffer_matches(
{ filetype = { "aerial", "dapui_.", "neo%-tree", "NvimTree" } },
vim.api.nvim_win_get_buf(self.winid)
)
end,
provider = function(self) return string.rep(" ", vim.api.nvim_win_get_width(self.winid) + 1) end,
hl = { bg = "tabline_bg" },
},
status.heirline.make_buflist(status.component.tabline_file_info()), -- component for each buffer tab
status.component.fill { hl = { bg = "tabline_bg" } }, -- fill the rest of the tabline with background color
{ -- tab list
condition = function() return #vim.api.nvim_list_tabpages() >= 2 end, -- only show tabs if there are more than one
status.heirline.make_tablist { -- component for each tab
provider = status.provider.tabnr(),
hl = function(self)
return status.hl.get_attributes(status.heirline.tab_type(self, "tab"), true)
end,
},
{ -- close button for current tab
provider = status.provider.close_button { kind = "TabClose", padding = { left = 1, right = 1 } },
hl = status.hl.get_attributes("tab_close", true),
on_click = { callback = function() require("astronvim.utils.buffer").close_tab() end, name = "heirline_tabline_close_tab_callback" },
},
},
}
opts.statuscolumn = { -- statuscolumn
status.component.foldcolumn(),
status.component.fill(),
status.component.numbercolumn(),
status.component.signcolumn(),
}
-- return the final configuration table
return opts
end,
},
},
}Default Statusline With Mode Text
Some users want to be able to add the mode text to their statusline easily, AstroNvim’s new astronvim.utils.status lua module as well as Heirline make that very easy to do in their user configuration file.
Minimal user/init.lua that adds the mode text to the statusline:
return {
plugins = {
{
"rebelot/heirline.nvim",
opts = function(_, opts)
local status = require("astronvim.utils.status")
opts.statusline = { -- statusline
hl = { fg = "fg", bg = "bg" },
status.component.mode { mode_text = { padding = { left = 1, right = 1 } } }, -- add the mode text
status.component.git_branch(),
status.component.file_info { filetype = {}, filename = false, file_modified = false },
status.component.git_diff(),
status.component.diagnostics(),
status.component.fill(),
status.component.cmd_info(),
status.component.fill(),
status.component.lsp(),
status.component.treesitter(),
status.component.nav(),
-- remove the 2nd mode indicator on the right
}
-- return the final configuration table
return opts
end,
},
},
}Replicate NvChad Statusline
NvChad comes with a very specific statusline configuration that a lot of people like, so we figured it would be a nice exercise of the extensibility of our astronvim.utils.status API to show how to build that statusline in AstroNvim. Warning: This is a fairly complicated example and is meant to be used by people who want it and to demonstrate how much you can customize the statusline.
Minimal user/init.lua that recreates the NvChad statusline in AstroNvim:
return {
-- add new user interface icon
icons = {
VimIcon = "",
ScrollText = "",
GitBranch = "",
GitAdd = "",
GitChange = "",
GitDelete = "",
},
-- modify variables used by heirline but not defined in the setup call directly
heirline = {
-- define the separators between each section
separators = {
left = { "", " " }, -- separator for the left side of the statusline
right = { " ", "" }, -- separator for the right side of the statusline
tab = { "", "" },
},
-- add new colors that can be used by heirline
colors = function(hl)
local get_hlgroup = require("astronvim.utils").get_hlgroup
-- use helper function to get highlight group properties
local comment_fg = get_hlgroup("Comment").fg
hl.git_branch_fg = comment_fg
hl.git_added = comment_fg
hl.git_changed = comment_fg
hl.git_removed = comment_fg
hl.blank_bg = get_hlgroup("Folded").fg
hl.file_info_bg = get_hlgroup("Visual").bg
hl.nav_icon_bg = get_hlgroup("String").fg
hl.nav_fg = hl.nav_icon_bg
hl.folder_icon_bg = get_hlgroup("Error").fg
return hl
end,
attributes = {
mode = { bold = true },
},
icon_highlights = {
file_icon = {
statusline = false,
},
},
},
plugins = {
{
"rebelot/heirline.nvim",
opts = function(_, opts)
local status = require("astronvim.utils.status")
opts.statusline = {
-- default highlight for the entire statusline
hl = { fg = "fg", bg = "bg" },
-- each element following is a component in astronvim.utils.status module
-- add the vim mode component
status.component.mode {
-- enable mode text with padding as well as an icon before it
mode_text = { icon = { kind = "VimIcon", padding = { right = 1, left = 1 } } },
-- surround the component with a separators
surround = {
-- it's a left element, so use the left separator
separator = "left",
-- set the color of the surrounding based on the current mode using astronvim.utils.status module
color = function() return { main = status.hl.mode_bg(), right = "blank_bg" } end,
},
},
-- we want an empty space here so we can use the component builder to make a new section with just an empty string
status.component.builder {
{ provider = "" },
-- define the surrounding separator and colors to be used inside of the component
-- and the color to the right of the separated out section
surround = { separator = "left", color = { main = "blank_bg", right = "file_info_bg" } },
},
-- add a section for the currently opened file information
status.component.file_info {
-- enable the file_icon and disable the highlighting based on filetype
file_icon = { padding = { left = 0 } },
filename = { fallback = "Empty" },
-- add padding
padding = { right = 1 },
-- define the section separator
surround = { separator = "left", condition = false },
},
-- add a component for the current git branch if it exists and use no separator for the sections
status.component.git_branch { surround = { separator = "none" } },
-- add a component for the current git diff if it exists and use no separator for the sections
status.component.git_diff { padding = { left = 1 }, surround = { separator = "none" } },
-- fill the rest of the statusline
-- the elements after this will appear in the middle of the statusline
status.component.fill(),
-- add a component to display if the LSP is loading, disable showing running client names, and use no separator
status.component.lsp { lsp_client_names = false, surround = { separator = "none", color = "bg" } },
-- fill the rest of the statusline
-- the elements after this will appear on the right of the statusline
status.component.fill(),
-- add a component for the current diagnostics if it exists and use the right separator for the section
status.component.diagnostics { surround = { separator = "right" } },
-- add a component to display LSP clients, disable showing LSP progress, and use the right separator
status.component.lsp { lsp_progress = false, surround = { separator = "right" } },
-- NvChad has some nice icons to go along with information, so we can create a parent component to do this
-- all of the children of this table will be treated together as a single component
{
-- define a simple component where the provider is just a folder icon
status.component.builder {
-- astronvim.get_icon gets the user interface icon for a closed folder with a space after it
{ provider = require("astronvim.utils").get_icon "FolderClosed" },
-- add padding after icon
padding = { right = 1 },
-- set the foreground color to be used for the icon
hl = { fg = "bg" },
-- use the right separator and define the background color
surround = { separator = "right", color = "folder_icon_bg" },
},
-- add a file information component and only show the current working directory name
status.component.file_info {
-- we only want filename to be used and we can change the fname
-- function to get the current working directory name
filename = { fname = function(nr) return vim.fn.getcwd(nr) end, padding = { left = 1 } },
-- disable all other elements of the file_info component
file_icon = false,
file_modified = false,
file_read_only = false,
-- use no separator for this part but define a background color
surround = { separator = "none", color = "file_info_bg", condition = false },
},
},
-- the final component of the NvChad statusline is the navigation section
-- this is very similar to the previous current working directory section with the icon
{ -- make nav section with icon border
-- define a custom component with just a file icon
status.component.builder {
{ provider = require("astronvim.utils").get_icon "ScrollText" },
-- add padding after icon
padding = { right = 1 },
-- set the icon foreground
hl = { fg = "bg" },
-- use the right separator and define the background color
-- as well as the color to the left of the separator
surround = { separator = "right", color = { main = "nav_icon_bg", left = "file_info_bg" } },
},
-- add a navigation component and just display the percentage of progress in the file
status.component.nav {
-- add some padding for the percentage provider
percentage = { padding = { right = 1 } },
-- disable all other providers
ruler = false,
scrollbar = false,
-- use no separator and define the background color
surround = { separator = "none", color = "file_info_bg" },
},
},
}
-- return the final options table
return opts
end,
},
},
}Replicate Visual Studio Code Winbar
Visual Studio Code has a default bar at the top of files that many users may prefer to AstroNvim’s default. Their winbar shows the path to the current file (relative to the working directory) along with the LSP provided breadcrumbs. This is achievable through our status API as well!
Minimal user/init.lua that recreates the winbar in Visual Studio Code:
return {
plugins = {
{
"rebelot/heirline.nvim",
opts = function(_, opts)
local status = require "astronvim.utils.status"
opts.winbar = { -- create custom winbar
-- store the current buffer number
init = function(self) self.bufnr = vim.api.nvim_get_current_buf() end,
fallthrough = false, -- pick the correct winbar based on condition
-- inactive winbar
{
condition = function() return not status.condition.is_active() end,
-- show the path to the file relative to the working directory
status.component.separated_path { path_func = status.provider.filename { modify = ":.:h" } },
-- add the file name and icon
status.component.file_info {
file_icon = { hl = status.hl.file_icon "winbar", padding = { left = 0 } },
file_modified = false,
file_read_only = false,
hl = status.hl.get_attributes("winbarnc", true),
surround = false,
update = "BufEnter",
},
},
-- active winbar
{
-- show the path to the file relative to the working directory
status.component.separated_path { path_func = status.provider.filename { modify = ":.:h" } },
-- add the file name and icon
status.component.file_info { -- add file_info to breadcrumbs
file_icon = { hl = status.hl.filetype_color, padding = { left = 0 } },
file_modified = false,
file_read_only = false,
hl = status.hl.get_attributes("winbar", true),
surround = false,
update = "BufEnter",
},
-- show the breadcrumbs
status.component.breadcrumbs {
icon = { hl = true },
hl = status.hl.get_attributes("winbar", true),
prefix = true,
padding = { left = 0 },
},
},
}
return opts
end,
},
},
}