*lualine.txt* A blazing fast and easy to configure statusline *lualine_nvim* *lualine* Author: hoob3rt (https://github.com/hoob3rt) License: MIT License Repository: https://github.com/hoob3rt/lualine.nvim =============================================================================== LUALINE.NVIM *lualine_lualine.nvim* __ __ __ ______ __ __ __ __ ______ /\ \ /\ \/\ \ /\ __ \ /\ \ /\ \ /\ "-.\ \ /\ ___\ \ \ \____ \ \ \_\ \ \ \ __ \ \ \ \____ \ \ \ \ \ \-. \ \ \ __\ \ \_____\ \ \_____\ \ \_\ \_\ \ \_____\ \ \_\ \ \_\\"\_\ \ \_____\ \/_____/ \/_____/ \/_/\/_/ \/_____/ \/_/ \/_/ \/_/ \/_____/ A blazing fast and easy to configure neovim statusline written in pure lua. `lualine.nvim` requires neovim 0.5 ================================================================================ CONTENTS *lualine_contents* 1. lualine.nvim...........................................|lualine_lualine.nvim| 1.1. Performance comparison.................|lualine_performance_comparison| 1.2. Installation.....................................|lualine_installation| 1.2.1. vim-plug.......................................|lualine_vim-plug| 1.2.2.packer.nvim..................................|lualine_packer.nvim| 1.3. Usage and customization...............|lualine_usage_and_customization| 1.3.1. Starting lualine.......................|lualine_starting_lualine| 1.3.2. Setting theme.............................|lualine_setting_theme| 1.3.3. Changing separator...................|lualine_changing_separator| 1.3.4. Changing components.................|lualine_changing_components| 1.3.5. Building Custom components............|lualine_custom_components| 1.3.6. Custom options...........................|lualine_custom_options| 1.3.7. Using tabline as statusline...............|lualine_using_tabline| 1.3.8. Loading plugin extensions.....|lualine_loading_plugin_extensions| 1.3.9 Config examples.........................|lualine_config_examples| 1.3.9.1. Packer.nvim......|lualine_config_example_using_packer.nvim| 1.3.9.2 VIML example.......|lualine_full_config_example_inside_viml| 1.4. Contributing.....................................|lualine_contributing| 1.5. Screenshots.......................................|lualine_screenshots| ================================================================================ PERFORMANCE COMPARISON *lualine_performance_comparison* Unlike other statusline plugins lualine loads only defined components, nothing else. Startup time performance measured with an amazing plugin tweekmonster/startuptime.vim (https://github.com/tweekmonster/startuptime.vim) All times are measured with only `startuptime.vim` and given statusline plugin installed | clean vimrc | lualine | lightline | airline | | :------------: | :----------: | :----------: | :----------: | | 8.943 ms | 9.034 ms | 11.463 ms | 13.425 ms | -------------------------------------------------------------------------------- INSTALLATION *lualine_installation* VIM-PLUG *lualine_vim-plug* > Plug 'hoob3rt/lualine.nvim' " If you want to have icons in your statusline choose one of these Plug 'kyazdani42/nvim-web-devicons' Plug 'ryanoasis/vim-devicons' < PACKER.NVIM *lualine_packer.nvim* > use { 'hoob3rt/lualine.nvim', requires = {'kyazdani42/nvim-web-devicons', opt = true} } < -------------------------------------------------------------------------------- USAGE AND CUSTOMIZATION *lualine_usage_and_customization* Lualine has sections as shown below. > +-------------------------------------------------+ | A | B | C X | Y | Z | +-------------------------------------------------+ < Each sections holds it's components e.g. current vim's mode. Colorscheme of sections is mirrored, meaning section `A` will have the same colorscheme as section `Z` etc. Configuration is currently limited to lua, please use lua block or a separate lua file to configure lualine. STARTING LUALINE *lualine_starting_lualine* > require('lualine').setup{} < SETTING THEME *lualine_setting_theme* > options = {theme = 'gruvbox'} < All available themes are listed in THEMES.md (./THEMES.md) Please create a pr if you managed to port a popular theme before me, here is how to do it (./CONTRIBUTING.md). Tweeking themes~ You like a theme but would like to tweek some colors. You can do that in your config easily. Example: > local custom_gruvbox = require'lualine.themes.gruvbox' -- Chnage the background of lualine_c section for normal mode custom_gruvbox.normal.c.bg = '#112233' -- rgb colors are supported require'lualine'.setup{ options = { theme = custom_gruvbox }, ... } < You can checkout structure of a lualine theme [here](https://github.com/hoob3rt/lualine.nvim/blob/master/CONTRIBUTING.md#adding-a-theme) CHANGING SEPARATOR IN SECTION *lualine_changing_separator* Lualine defines two kinds of seperators. One is for sections and other is for components. Default section seperators are '', '' and component separators are '', ''.They require powerline patched fonts. But you can easily change yours to something else like below. > options = { section_separators = {'', ''}, component_separators = {'', ''} } or disable it > options = {section_separators = '', component_separators = ''} < CHANGING COMPONENTS IN LUALINE SECTIONS *lualine_changing_components* Lualine defaults~ > sections = { lualine_a = { 'mode' }, lualine_b = { 'branch' }, 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 = { } } < Available components~ general~ * branch (git branch) * diagnostics (diagnostics count from your prefered source) * encoding (file encoding) * fileformat (file format) * filename * filetype * hostname * location (location in file in line:column format) * mode (vim mode) * progress (%progress in file) * diff (git diff status) -------------------------------------------------------------------------------- BUILDING YOUR COMPONENTS *lualine_custom_components* Using custom functions as lualine component~ You can define a custom function as a lualine component > local function hello() return [[hello world]] end sections = {lualine_a = {hello}} < Using vim functions as lualine component~ You can use vim functions as a lualine component > sections = {lualine_a = {'FugitiveHead'}} < Using variables as lualine component~ You can use variables from vim. Variables from g:, v:, t:, w:, b:, o, go:, vo:, to:, wo:, bo: scopes can be used. Scopes ending with o are options usualy accessed with `&` in vimscript > sections = {lualine_a = {'g:coc_status', 'bo:filetype'}} < Using lua expressions as lualine component~ You can use any valid lua expression as a component . This allows global variables to be used as a component too. Even require statements can be used to access values returned by specific scripts. One liner functions can be inlined by utilizeing this . For exmaple this will show day of the week. And 2nd one will display current value of global variabke data. > sections = {lualine_c = {"os.data('%a')", 'data'}} < -------------------------------------------------------------------------------- CUSTOM OPTIONS FOR COMPONENTS *lualine_custom_options* Options for components~ ====================== Available options:~ Options can change the way a component behave. There are two kinds of options some that work on every kind of component. Even the ones you create like custom function component . And some that only work on specific component. Detailed list of available options are given below. Global options~ These options are available for all components. option (default_value) ------ --------------- • icons_enabled (true) Displays icons on components You should have nerd-fonts supported fonts to see icons properly. Supported components: branch, fileformat, filetype, location, diagnostics • icon (depends on component) displays an icon infront of a component Supported components: all • padding (1) spaces on left and right Supported components: all • left_padding (1) spaces on left Supported components: all • right_padding (1) spaces on right Supported components: all • separator (component_separators) which separator to use at end of component Supported components: all • upper (false) Displayed in upper case Supported components: all • lower (false) Displayed in lower case Supported components: all • format (nil) Takes a function . The funtion gets the result of component as argument and it's return value is displayed. So this function can parse and format the output as user wants. Supported components: all Example: `lualine.options.icons_enabled = true` Component specific options --------------- As mentioned above, all global options can be applied to specific components. However there are some options which are component-only (you cannot set them as globals) option (default_value) ------ --------------- • icon (differs for each component) displays an icon infront of a component • condition (nil) Takes a function. The component is loaded if the function returns true otherwise not. It can be used to load some comoonents on specific cases. • color (Theme colors) color option can be used to set custom color to a component Color format: `lua color = {fg = '#rrggbb', bg= '#rrggbb', gui='style'}` the members of color table are optional and default to theme Color option can also be a string containing highlight group name > color = "WarningMsg"` < One neat trick set the color to highlight group name then change that highlight with :hi command to change color of that component at runtime. Using global options~ Global options can be set in two ways. One is as part of options table in setup. > require'lualine'.setup{ options = { icons_enabled = true, padding = 2, } } < When set this way these values work as default for all component. These defaults can be overwritten by setting option as part of component configuration like following. > lualine_a = { -- Displays only first char of mode name {'mode', format=function(mode_name) return mode_name:sub(1,1) end}, -- Disables icon for branch component {'branch', icons_enabled=false}, }, lualine_c = { -- Displays filename only when window is wider then 80 {'filename', condition=function() return vim.fn.winwidth(0) > 80 end}, } < Component specific options~ In addition, some components have unique options. • diagnostics~ • sources (nil) displays diagnostic count from defined source. array containing one or many string from set {'nvim_lsp', 'coc', 'ale', 'vim_lsp'} • sections ({'error', 'warn', 'info'}) displays diagnostics of defined severity. array containing one or many string from set {'error', 'warn', 'info'} • color_error (DiffDelete foreground color) changes diagnostic's error section foreground color. color in #rrggbb format • color_warn (DiffText foreground color) changes diagnostic's warn section foreground color color in #rrggbb format • color_info (Normal foreground color) changes diagnostic's info section foreground color color in #rrggbb format • symbols (icons_enabled: true -> {error = ' ', warn = ' ', info = ' '}) (icons_enabled: false -> {error = 'E:', warn = 'W:', info = 'I:'}) changes diagnostic's symbol characters. You can set one or more symbols for each level. > { 'diagnostics', symbols = { -- set the error symbol and use defaults for warn and info. error = '!!', }, } < • filename~ • file_status (true) Displays file status (readonly status, modified status) • full_path (false) Displays relative path if set to `true`, absolute path if set to `false` • shorten (true) if `full_path` is `true` and `shorten` is `false` it shortens absolute path `aaa/bbb/ccc/file` to `a/b/c/file` • symbols (`{modified = '[+]', readonly = '[-]'}`) changes status symbols • fileformat~ • icons_enabled (true) Whether to displays icon before component. Colors are automaticaly extracted from colorscheme . If you want to change any of those you can use options given below. • diff~ • colored (true) displays diff status in color if set to `true` • color_added (DiffAdd foreground color) Changes diff's added section foreground color Color in `#rrggbb` format • color_modified (DiffChange foreground color) Changes diff's changed section foreground color Color in `#rrggbb` format • color_removed (DiffDelete foreground color) Changes diff's removed section foreground color Color in `#rrggbb` format • symbols (`{added = '+', modified = '~', removed = '-'}`) changes diff's symbols Color in `#rrggbb` format < Component specific options can only be set with component configs. Example:~ > sections = { lualine_b = { {'branch', icon = '', upper = true, color = {fg = '#00aa22'}}, { 'filename', full_name = true, shorten = true, format = function(name) -- Capitalize first charecter of filename to capital. local path, fname = name:match('(.*/)(.*)') if not path then path = ''; fname = name end return path .. fname:sub(1, 1):upper() .. fname:sub(2, #fname) end } } } ------------------------------------------------------------------------------- USING TABLINE AS STATUSLINE *lualine_using_tabline* You can use lualine to display components in tabline . The sections, configurations and highlights are same as statusline. > tabline = { lualine_a = { }, lualine_b = { 'branch' }, lualine_c = { 'filename' }, lualine_x = { }, lualine_y = { }, lualine_z = { }, } < This will show branch and filename component in top of neovim inside tabline . You can also completely move your statuline to tabline by configuring lualine.tabline instead of lualine.sections & lualine.inactive_sections and setting them to empty > tabline = { ...... } sections = {} inactive_sections = {} < -------------------------------------------------------------------------------- LOADING PLUGIN EXTENSIONS *lualine_loading_plugin_extensions* Lualine extensions change statusline appearance for a window/buffer with a plugin loaded e.g. junegunn/fzf.vim (https://github.com/junegunn/fzf.vim) By default no plugin extension are loaded to improve performance. If you are using a plugin which is supported you can load it this way: > extensions = { 'fzf' } < Available extensions * fugitive * fzf * nerdtree * chadtree * nvim-tree -------------------------------------------------------------------------------- CONGIG EXAMPLES *lualine_config_examples* Lua config example > use { 'hoob3rt/lualine.nvim', requires = {'kyazdani42/nvim-web-devicons', opt = true}, config = function() require('lualine').setup{ options = { theme = 'gruvbox', section_separators = {'', ''}, component_separators = {'', ''}, icons_enabled = true, }, sections = { lualine_a = { {'mode', upper = true} }, lualine_b = { {'branch', icon = ''} }, lualine_c = { {'filename', file_status = true} }, 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 = { } }, extensions = { 'fzf' } } end } < -------------------------------------------------------------------------------- Vimscript config example > let g:lualine = { \'options' : { \ 'theme' : 'gruvbox', \ 'section_separators' : ['', ''], \ 'component_separators' : ['', ''], \ 'icons_enabled' : v:true, \}, \'sections' : { \ 'lualine_a' : [ ['mode', {'upper': v:true,},], ], \ 'lualine_b' : [ ['branch', {'icon': '',}, ], ], \ 'lualine_c' : [ ['filename', {'file_status': v:true,},], ], \ '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' : [ ], \}, \'extensions' : [ 'fzf' ], \} lua require("lualine").setup() < ------------------------------------------------------------------------------- vim:tw=80:sw=4:ts=8:noet:ft=help:norl:et: