heirline-components.nvim

Distro agnostic components for your Neovim heirline config.

This is how the components above look on the statusline.

Table of contents

• Why
• How to install
• How to use
• Example config
• Components
• Available options
• Events (optional)
• FAQ

Why

Heirline is a engine to create your own Neovim user interface. This comes at a price though: increased complexity. To avoid that problem, I've decided to compile this collection of components you can fork and modify. That way you have a safe and well tested starting point to hopefuly save you a lot of time.

How to install

Add it as a dependency of heirline

{
  "rebelot/heirline.nvim",
  dependencies = { "Zeioth/heirline-components.nvim" }
  opts = {},
    config = function(_, opts)
      local heirline = require "heirline"
      local heirline_components = require "heirline-components.all"

      -- Setup
      heirline_components.init.subscribe_to_events()
      heirline.load_colors(heirline_components.hl.get_colors())
      heirline.setup(opts)
    end,
}

Some extra features will only be available if you have the next plugins installed:

• lewis6991/gitsigns.nvim
• nvim-telescope/telescope.nvim
• zeioth/compiler.nvim
• mfussenegger/nvim-dap
• echasnovski/mini.bufremove
• nvim-neo-tree/neo-tree.nvim
• stevearc/aerial.nvim
• folke/zen-mode.nvim
• linux-cultist/venv-selector.nvim

How to use

You can add a component to your heirline config as

require("heirline-components.all").component.some_component()

Normally you will use components directly like in this example. But in some cases you can customize a component. Refer to every specific component for more info.

Example config

You can find the example config we use for NormalNvim here.

Components

Tabline components

This is the heirline line you see at the top of the screen.

Component	Description
tabline_buffers	Tabline component to display the listed buffers of the current tabpage.
tabline_tabpages	Tabline component to display the available tabpages.
tabline_conditional_padding	Tabine component to add padding under certain conditions. By default it adds padding when you open a side panel like neotree, or aerial, according to the panel width.

You can control the tabline from your keymappings with heirline-components.buffer.

Winbar components

This is the heirline line you see under the tabline.

Component	Description
winbar_when_inactive	If present, it will empty the winbar while the buffer doesn't have the focus (like in the terminal, neotree, etc).
breadcrumbs	Winbar component to display a LSP based breadcrumbs section.
compiler_play	Winbar component to display a button to open compiler.nvim.
compiler_stop	Winbar component to display a button to dispose all compiler.nvim tasks.
compiler_redo	Winbar component to display a button to redo the last selected compiler.nvim action.
compiler_build_type	Winbar component to toggle the current build type of your cmake or gradle project on compiler.nvim.
neotree	Winbar component to display a button to toggle neotree.
aerial	Winbar component to display a button to toggle aerial.
zen_mode	Winbar component to display a button to toggle zen-mode.
write_buffer	Winbar component to display a button to write the current buffer.
write_all_buffers	Winbar component to display a button to write all loaded buffers.

Statuscolumn components

This is the heirline column you see at the left of the screen.

Component	Description
foldcolumn	Statuscolumn component to fold/unfold lines.
numbercolumn	Statuscolumn component to display the line numbers.
signcolumn	Statuscolumn component to indicate the lines that have been changed since the last commit (gitsigns hunks).

Statusline components

This is the heirline line you see at the bottom of the screen.

Component	Description
fill	Statusline component to fill the empty space of the bar.
file_info	Statusline component to display the filetype of the current buffer.
file_encoding	Statusline component to display operative system and file encoding.
nav	Statusline component to display a nativation area, with line number, and the current navigation %.
cmd_info	Statusline component to display information about some commands, like a macro recording indicator, or the search results.
mode	Statusline component for a mode chage. By default it only show colors, but it can be configured to show NORMAL, INSERT... etc like in classic vim.
git_branch	Statusline component to display the current git branch.
git_diff	Statusline component to display the current git diff (added, removed, changed).
diagnostics	Statusline component to display a diagnostics section (errors, warnings, info).
treesitter	Statusline component to display a indicator when Treesitter is enabled.
lsp	Statusline component to display the loaded lsp clients. Or their current load % if they haven't loaded yet. Similar to the plugin noice.nvim.
virtual_env	Statusline component to display the current python virtual env.
compiler_state	Statusline component to display a spinner while compiler.nvim is running. This component is also compatible with overseer.

Available options

You can customize icons and colors in a easy way.

Option
icons
colors

For example:

"rebelot/heirline.nvim",
dependencies = {
  {
    "Zeioth/heirline-components.nvim",
    opts = {
      icons = { DiagnosticError = ";D" }
      colors = nil
    }
  }
}

Events (Optional)

Heirline-components listen for two different events:

Event	Description
ColorScheme	When you trigger this event, Heirline-components will reload its colors.
User HeirlineComponentsTablineBuffersUpdated	This event is automatically triggered every time a buffer is added or deleted from the component tabline_buffers (which is ruled by vim.t.bufs). This is useful if you only want to show the tabline when more that 1 buffer is opened. To do so, you can create a autocmd to listen to this event. Then make it set the vim.opt.showtabline = 2 if #vim.t.bufs > 1.

So if you experience issues with colors or outdated tabline info, trigger these events with :doautocmd.

Credits

Currently, most of the GPL3 lua components this plugin use come from AstroNvim and NormalNvim. So please support both projects if you enjoy this plugin.

FAQ

• How can I contribute with a component? Clone this repo. Go to core.component.lua and create yours there. Then open a PR.
• How do components work? A component is made of providers. So you can use providers to build your component. Aditionally, conditions are used to decide when a component should be displayed. These components have been tested on nvim v0.10+
• How can I avoid breaking changes? Always use the components by importing heirline-components.all. That way internal changes won't affect you. If you wanna be extra sure, you can also lock the plugin version in your package manager to avoid getting updates.

🌟 Support the project

If you want to help me, please star this repository to increase the visibility of the project.