DOCSEARCHbyAlgolia
Submit Docs

lualine.nvim

repository·master·Indexed 27 days ago

https://github.com/nvim-lualine/lualine.nvim

A fast and highly configurable statusline plugin for Neovim written in Lua. It supports custom components, themes, and extensions for various filetypes, as well as configuration for the tabline and winbar. Requires Neovim >= 0.7.

Tokens
3.5K
Snippets
11
Records
20
Agent score
43%

What's inside lualine.nvim

  1. Use custom components in lualine

    master

    Lualine sections can contain various types of components:

    • Lua functions: Return a string.
    • Vim functions: Call a Vimscript function by name.
    • Vim statusline items: Use standard % syntax (e.g., %t%m).
    • Vim variables: Use scope prefixes like g:, v:, b:, etc.
    • Lua expressions: Any valid Lua expression (oneliners, require statements, etc.).

  2. Configure Tabline and Winbar

    master

    Lualine can be used to drive the Neovim tabline and winbar (available in Neovim 0.8+). The configuration structure for these is identical to the statusline. You can also configure an inactive_winbar for non-focused windows.

    -- Configure tabline
tabline = {
  lualine_a = {'buffers'},
  lualine_b = {'branch'},
  lualine_c = {'filename'},
  lualine_z = {'tabs'}
}

-- Configure winbar
winbar = {
  lualine_c = {'filename'}
}

  3. Use lualine extensions

    master

    Extensions modify the statusline appearance based on specific filetypes. By default, no extensions are loaded. Load them via the extensions option in setup().

    Available extensions include: aerial, assistant, avante, chadtree, ctrlspace, fern, fugitive, fzf, lazy, man, mason, mundo, neo-tree, nerdtree, nvim-dap-ui, nvim-tree, oil, overseer, quickfix, symbols-outline, toggleterm, and trouble.

  4. Install lualine.nvim

    master

    Install lualine.nvim using your preferred Neovim plugin manager. It is recommended to also install nvim-tree/nvim-web-devicons to enable icon support in your statusline. Note that using icons requires a patched font (like a Nerd Font) installed on your system.

    Requirements:

    • Neovim >= 0.7
    • For older versions, use compatibility tags (e.g., compat-nvim-0.5)
    ### [vim.pack](https://neovim.io/doc/user/pack/#vim.pack) (Only for neovim 0.12)

```lua
vim.pack.add({
    'https://github.com/nvim-tree/nvim-web-devicons',
    'https://github.com/nvim-lualine/lualine.nvim'
})

    vim-plug

    Plug 'nvim-lualine/lualine.nvim'
" If you want to have icons in your statusline choose one of these
Plug 'nvim-tree/nvim-web-devicons'

    packer.nvim

    use {
  'nvim-lualine/lualine.nvim',
  requires = { 'nvim-tree/nvim-web-devicons', opt = true }
}

    lazy.nvim

    {
    'nvim-lualine/lualine.nvim',
    dependencies = { 'nvim-tree/nvim-web-devicons' }
}

  9. Configure lualine with default options

    master

    Use require('lualine').setup() with an options table to customize the statusline, sections, and themes. The configuration includes options for global behavior, sections for the statusline, inactive_sections for inactive windows, tabline, winbar, and extensions.

    require('lualine').setup {
  options = {
    icons_enabled = true,
    theme = 'auto',
    component_separators = { left = '', right = ''},
    section_separators = { left = '', right = ''},
    disabled_filetypes = {
      statusline = {},
      winbar = {},
    },
    ignore_focus = {},
    always_divide_middle = true,
    always_show_tabline = true,
    globalstatus = false,
    refresh = {
      statusline = 1000,
      tabline = 1000,
      winbar = 1000,
      refresh_time = 16,
      events = {
        'WinEnter',
        'BufEnter',
        'BufWritePost',
        'SessionLoadPost',
        'FileChangedShellPost',
        'VimResized',
        'Filetype',
        'CursorMoved',
        'CursorMovedI',
        'ModeChanged',
      },
    }
  },
  sections = {
    lualine_a = {'mode'},
    lualine_b = {'branch', 'diff', 'diagnostics'},
    lualine_c = {'filename'},
    lualine_x = {'encoding', 'fileformat', 'filetype'},
    lualine_y = {'progress'},
    lualine_z = {'location'}
  },
  inactive_sections = {
    lualine_a = {},
    lualine_b = {},
    lualine_c = {'filename'},
    lualine_x = {'location'},
    lualine_y = {},
    lualine_z = {}
  },
  tabline = {},
  winbar = {},
  inactive_winbar = {},
  extensions = {}
}

  10. Configure separators

    master

    Lualine uses two types of separators:

    • section_separators: Separators between major sections (a, b, c vs x, y, z).
    • component_separators: Separators between individual components within a section.

    Use left and right keys to define them. To disable them, pass an empty string.

    options = {
  section_separators = { left = '', right = '' },
  component_separators = { left = '', right = '' }
}

  12. Refresh lualine manually

    master

    While lualine refreshes automatically based on timers and events, you can force a refresh using require('lualine').refresh().

    Arguments:

    • scope: 'all', 'tabpage', or 'window' (default: 'all').
    • place: Table of segments to refresh: {'statusline', 'winbar', 'tabline'}.
    • force: Boolean. If true, bypasses the refresh queue and processes the refresh immediately.