OXY2DEV/ui.nvim
github
110
3
2
3
💻 ui.nvim
A blueprint/template/guide to customize Neovim's UI using Lua.
🤔 So, what is this?
This is a simple customisable UI plugin written in Lua for you to play around with!
If you ever worked on modifying Neovim's UI, it might feel frustrating to work with. The docs(as of 0.11) don't go too deep into it either(as this is still experimental). This repository is meant to change that.
You no longer need to write boilerplate or handle errors without using messages or spend hours trying to figure put how to handle different Ui events. As this is also usable as a plugin, you don't have to worry about things being outdated either!
📦 What's included?
As of now, this plugin comes with the following things,
- Basic UI event handler(separated into parts for better readability & portability).
- Working example on handling most events.
- Type definitions for different events.
- Helpful
heads upfor various quirky scenarios. - Basic state manager for command-line & messages.
- A simple logger for logging messages(WIP).
A bunch of helpers are also provided,
- Dynamic highlight groups(see
ui/highlights.lua). This automatically makes the plugin supported by almost all colorschemes. - Utility function for showing
virtual text&UI contentsinto a buffer as actual text with highlights! - Utility function for turning
virtual textinto statuscolumn content. This makes adding complex signs on wrapped lines much easier! - A basic reading time calculator. This makes long messages stay on the screen for longer durations.
- A basic value evaluator. Useful if you want to support
functionsas configuration options without usingconditionalseverywhere.
📜 Where to start?
I recommend reading :h ui.txt first(don't worry if you don't understand it).
[!TIP] The wiki is also available in vimdoc(see
:h ui.nvim)!
You can check the wiki for the explanations and read the source files for the actual implementation.
[!NOTE] If you want to help, feel free to point out issues with the wiki!
✨ Features
Custom UI for the command-line. It supports,
- Block mode support(with context lines too).
- Changing appearance(background color, filetype etc.) based on command-line state.
- Custom titles.
- Concealing text(for
:lua,:=,:!etc.). - Syntax highlighting(tree-sitter based).
Custom UI for the message. It supports,
- Ignoring specific messages.
- Changing message content and highlighting.
- Separate window(s) for
confirmationandliststyle messages. - Custom
:messageswindow with support for multiple message providers(vim&internal). showcmdsupport.
Custom UI for the pop-up menu. It supports,
- Icons for different entry types.
- Changing how each entry is shown(padding, background, select color).
Dynamic highlight groups.
🤦♂️ Known issues
Pum menu giving incorrect position & size in completion events. Breaks:
mini.completionGoing into
command modeafter a write causes duplicate message with wrong kind. Breaks:nvim-0.11
📝 Requirements
- Neovim 0.11, though 0.10 also works for the most part.
📥 Installation
💤 lazy.nvim
[!WARNING] Do not lazy load this plugin! It is supposed to be loaded before other plugins(right after loading your
colorscheme).
For plugins.lua users,
{
"OXY2DEV/ui.nvim",
lazy = false
};
For plugins/ui.lua users,
return {
"OXY2DEV/ui.nvim",
lazy = false
};
🦠 Mini.deps
local MiniDeps = require("mini.deps");
MiniDeps.add({
source = "OXY2DEV/ui.nvim"
});
🌒 Rocks.nvim
[!WARNING]
luarocks packagemay sometimes be a bit behindmain.
:Rocks install ui.nvim
🔩 Configuration
The plugin can be configured via the setup() function. You can check the default configuration table here.
A simplified version of the configuration table is given below,
require("ui").setup({
popupmenu = {
enable = true,
winconfig = {},
tooltip = nil,
styles = {
default = {
padding_left = " ",
padding_right = " ",
icon = nil,
text = nil,
normal_hl = nil,
select_hl = "CursorLine",
icon_hl = nil
},
example = {
condition = function ()
return true;
end,
icon = "I "
}
}
},
cmdline = {
enable = true,
styles = {
default = {
cursor = "Cursor",
filetype = "vim",
icon = { { "I ", "@comment" } },
offset = 0,
title = nil,
winhl = ""
},
example = {
condition = function ()
return true;
end,
cursor = "@comment"
}
}
},
message = {
enable = true,
message_winconfig = {},
list_winconfig = {},
confirm_winconfig = {},
history_winconfig = {},
ignore = function ()
return false:
end,
showcmd = {
max_width = 10,
modifier = nil
},
msg_styles = {
default = {
duration = 500,
modifier = nil,
decorations = {
icon = { { "I " } }
}
},
example = {
condition = function ()
return true;
end,
decorations = {
icon = { { "B " } }
}
}
},
is_list = function ()
return false;
end,
list_styles = {
default = {
modifier = nil,
row = nil,
col = nil,
width = nil,
height = nil,
winhl = nil
},
example = {
condition = function ()
return true;
end,
border = "rounded"
}
},
confirm_styles = {
default = {
modifier = nil,
row = nil,
col = nil,
width = nil,
height = nil,
winhl = nil
},
example = {
condition = function ()
return true;
end,
border = "rounded"
}
}
}
});
[!TIP] You can call the
setup()as many times as you want!
💻 Commands
You can run :UI to toggle the custom UI. It has the following sub-commands,
enableEnables custom UI.disableDisables custom UI.toggleToggles custom UI.
🎨 Highlight groups
By default this plugin comes with the following highlight groups,
UICmdlineDefaultUICmdlineDefaultIconUICmdlineLuaUICmdlineLuaIconUICmdlineEvalUICmdlineEvalIconUICmdlineSearchUpUICmdlineSearchUpIconUICmdlineSearchDownUICmdlineSearchDownIconUICmdlineSubstituteUICmdlineSubstituteIconUIMessageDefaultUIMessageOkUIMessageInfoUIMessageInfoSignUIMessageWarnUIMessageWarnSignUIMessageErrorUIMessageErrorSignUIMessagePaletteUIMessageErrorSignUIHistoryKeymapUIHistoryDescUIMenuSelectUIMenuKeymap