lualine.nvim

code size license

A blazing fast and easy to configure Neovim statusline written in Lua.

lualine.nvim requires Neovim >= 0.7.

For previous versions of neovim please use compatability tags for example compat-nvim-0.5

Contributing

Feel free to create an issue/PR if you want to see anything else implemented. If you have some question or need help with configuration, start a discussion.

Please read CONTRIBUTING.md before opening a PR. You can also help with documentation in the wiki.

Screenshots

Here is a preview of what lualine can look like.

Screenshots of all available themes are listed in THEMES.md

For those who want to break the norms, you can create custom looks for lualine.

Example :

evil_lualine <img width='700' src='https://user-images.githubusercontent.com/13149513/113875129-4453ba00-97d8-11eb-8f21-94a9ef565db3.png'/>
slanted-gaps <img width='700' src='https://user-images.githubusercontent.com/13149513/143395518-f6d6f748-c1ca-491b-9dab-246d0a8cf23f.png'/>
bubbles <img width='700' src='https://user-images.githubusercontent.com/20235646/131350468-fc556196-5f46-4bfe-a72e-960f6a58db2c.png'/>
cosmicink <img width='700' src='https://github.com/user-attachments/assets/c8d3e4ba-4997-42e9-a1bb-d5e2a444bbfd'/>

Performance compared to other plugins

Unlike other statusline plugins, lualine loads only the components you specify, and nothing else.

Startup time performance measured with an amazing plugin dstein64/vim-startuptime

Times are measured with a clean init.vim with only vim-startuptime, vim-plug and given statusline plugin installed. In control just vim-startuptime andvim-plug is installed. And measured time is complete startuptime of vim not time spent on specific plugin. These numbers are the average of 20 runs.

| control | lualine | lightline | airline | | :-----: | :-----: | :-------: | :-----: | | 17.2 ms | 24.8 ms | 25.5 ms | 79.9 ms |

Last Updated On: 18-04-2022

Installation

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' }
}

You'll also need to have a patched font if you want icons.

Usage and customization

Lualine has sections as shown below.

+-------------------------------------------------+
| A | B | C                             X | Y | Z |
+-------------------------------------------------+

Each sections holds its components e.g. Vim's current mode.

Configuring lualine in init.vim

All the examples below are in lua. You can use the same examples in .vim files by wrapping them in lua heredoc like this:

lua << END
require('lualine').setup()
END

For more information, check out :help lua-heredoc.

Default configuration

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, -- ~60fps
      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 = {}
}

If you want to get your current lualine config, you can do so with:

require('lualine').get_config()

Starting lualine

require('lualine').setup()

Setting a theme

options = { theme = 'gruvbox' }

All available themes are listed in THEMES.md.

Please create a PR if you managed to port a popular theme before us, here is how to do it.

Customizing themes

local custom_gruvbox = require'lualine.themes.gruvbox'

-- Change the background of lualine_c section for normal mode
custom_gruvbox.normal.c.bg = '#112233'

require('lualine').setup {
  options = { theme  = custom_gruvbox },
  ...
}

Theme structure is available here.

Separators

lualine defines two kinds of separators:

section_separators - separators between sections
component_separators - separators between the different components in sections

Note: if viewing this README in a browser, chances are the characters below will not be visible.

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

Here, left refers to the left-most sections (a, b, c), and right refers to the right-most sections (x, y, z).

Disabling separators

options = { section_separators = '', component_separators = '' }

Changing components in lualine sections

sections = {lualine_a = {'mode'}}

Available components

branch (git branch)
buffers (shows currently available buffers)
diagnostics (diagnostics count from your preferred source)
diff (git diff status)
encoding (file encoding)
fileformat (file format)
filename
filesize
filetype
hostname
location (location in file in line:column format)
mode (vim mode)
progress (%progress in file)
searchcount (number of search matches when hlsearch is active)
selectioncount (number of selected characters or lines)
tabs (shows currently available tabs)
windows (shows currently available windows)
lsp_status (shows active LSPs in the current buffer and a progress spinner)

Custom components

Lua functions as lualine component

local function hello()
  return [[hello world]]
end
sections = { lualine_a = { hello } }

Vim functions as lualine component

sections = { lualine_a = {'FugitiveHead'} }

Vim's statusline items as lualine component

sections = { lualine_c = {'%=', '%t%m', '%3p'} }

Vim variables as lualine component

Variables from g:, v:, t:, w:, b:, o:, to:, wo:, bo: scopes can be used.

See :h lua-vim-variables and :h lua-vim-options if you are not sure what to use.

sections = { lualine_a = { 'g:coc_status', 'bo:filetype' } }

Lua expressions as lualine component

You can use any valid lua expression as a component including:

oneliners
global variables
require statements

sections = { lualine_c = { "os.date('%a')", 'data', "require'lsp-status'.status()" } }

data is a global variable in this example.

Component options

Component options can change the way a component behave. There are two kinds of options:

global options affecting all components
local options affecting specific

Global options can be used as local options (can be applied to specific components) but you cannot use local options as global. Global option used locally overwrites the global, for example:

    require('lualine').setup {
      options = { fmt = string.lower },
      sections = { lualine_a = {
        { 'mode', fmt = function(str) return str:sub(1,1) end } },
                  lualine_b = {'branch'} }
    }

mode will be formatted with the passed function so only first char will be shown . On the other hand branch will be formatted with global formatter string.lower so it will be showed in lower case.

Available options

Global options

These are options that are used in options table. They set behavior of lualine.

Values set here are treated as default for other options that work in component level.

For example even though

Lualine.nvim

Install / Use

README