{"id":27992816,"url":"https://github.com/oxy2dev/ui.nvim","last_synced_at":"2025-05-08T18:43:01.434Z","repository":{"id":285880322,"uuid":"959646987","full_name":"OXY2DEV/ui.nvim","owner":"OXY2DEV","description":"A blueprint/template/guide to customize Neovim's UI using Lua.","archived":false,"fork":false,"pushed_at":"2025-05-03T04:55:26.000Z","size":3359,"stargazers_count":120,"open_issues_count":4,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-03T05:27:34.419Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OXY2DEV.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-03T06:01:59.000Z","updated_at":"2025-05-03T04:55:30.000Z","dependencies_parsed_at":"2025-04-03T07:22:06.764Z","dependency_job_id":"b9746e22-d7c4-4e38-a0ea-e5dc89ad5ff1","html_url":"https://github.com/OXY2DEV/ui.nvim","commit_stats":null,"previous_names":["oxy2dev/ui.nvim"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OXY2DEV%2Fui.nvim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OXY2DEV%2Fui.nvim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OXY2DEV%2Fui.nvim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OXY2DEV%2Fui.nvim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OXY2DEV","download_url":"https://codeload.github.com/OXY2DEV/ui.nvim/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253131639,"owners_count":21859046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-08T18:43:00.037Z","updated_at":"2025-05-08T18:43:01.423Z","avatar_url":"https://github.com/OXY2DEV.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💻 ui.nvim\n\n\u003cimg src=\"https://github.com/OXY2DEV/ui.nvim/blob/images/images/ui.nvim.png\"\u003e\n\u003cimg src=\"https://github.com/OXY2DEV/ui.nvim/blob/images/images/ui.nvim-cmdline.png\"\u003e\n\u003cimg src=\"https://github.com/OXY2DEV/ui.nvim/blob/images/images/ui.nvim-messages.png\"\u003e\n\u003cimg src=\"https://github.com/OXY2DEV/ui.nvim/blob/images/images/ui.nvim-popupmenu_cmp.png\"\u003e\n\nA blueprint/template/guide to customize Neovim's UI using Lua.\n\n\u003cdetails\u003e\u003c!--|fS--\u003e\n    \u003csummary\u003eExpand for advanced usage!\u003c/summary\u003e\n\n## 🤔 So, what is this?\n\nThis is a simple customisable UI plugin written in Lua for you to play around with!\n\nIf 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.\n\nYou 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!\n\n## 📦 What's included?\n\nAs of now, this plugin comes with the following things,\n\n- Basic UI event handler(separated into parts for better readability \u0026 portability).\n- Working example on handling *most* events.\n- Type definitions for different events.\n- Helpful `heads up` for various *quirky scenarios*.\n- Basic state manager for command-line \u0026 messages.\n- A simple logger for logging messages(WIP).\n\nA bunch of helpers are also provided,\n\n- Dynamic highlight groups(see `ui/highlights.lua`). This automatically makes the plugin supported by *almost* all colorschemes.\n- Utility function for showing `virtual text` \u0026 `UI contents` into a buffer as **actual text** with highlights!\n- Utility function for turning `virtual text` into statuscolumn content. This makes adding complex signs on wrapped lines much easier!\n- A basic reading time calculator. This makes long messages stay on the screen for longer durations.\n- A basic value evaluator. Useful if you want to support `functions` as configuration options without using `conditionals` everywhere.\n\n## 📜 Where to start?\n\nI recommend reading `:h ui.txt` first(don't worry if you don't understand it).\n\n\u003e[!TIP]\n\u003e The wiki is also available in vimdoc(see `:h ui.nvim`)!\n\nYou can check the [wiki](https://github.com/OXY2DEV/ui.nvim/wiki) for the explanations and read the source files for the actual implementation.\n\n\u003e[!NOTE]\n\u003e If you want to help, feel free to point out issues with the wiki!\n\n\u003c/details\u003e\u003c!--|fE--\u003e\n\n## ✨ Features\n\n- Custom UI for the command-line. It supports,\n    - Block mode support(with context lines too).\n    - Changing appearance(background color, filetype etc.) based on command-line state.\n    - Custom titles.\n    - Concealing text(for `:lua`, `:=`, `:!` etc.).\n    - Syntax highlighting(tree-sitter based).\n\n- Custom UI for the message. It supports,\n    - Ignoring specific messages.\n    - Changing message content and highlighting.\n    - Separate window(s) for `confirmation` and `list` style messages.\n    - Custom `:messages` window with support for multiple message providers(`vim` \u0026 `internal`).\n    - `showcmd` support.\n\n- Custom UI for the pop-up menu. It supports,\n    - Icons for different entry types.\n    - Changing how each entry is shown(padding, background, select color).\n\n- Dynamic highlight groups.\n\n## 🤦‍♂️ Known issues\n\n- Pum menu giving incorrect position \u0026 size in completion events(This is a missing feature of Neovim).\n  Breaks: `mini.completion`\n\n- In certain `redraw` events, the write message is shown for some reason(pretty sure this is an already reported bug).\n  Breaks: `nvim-0.11`\n\n## 📝 Requirements\n\n- Neovim 0.11, though 0.10 also works *for the most part*.\n\n## 📥 Installation\n\n### 💤 lazy.nvim\n\n\u003e[!WARNING]\n\u003e Do not lazy load this plugin! It is supposed to be loaded before other plugins(right after loading your `colorscheme`).\n\nFor `plugins.lua` users,\n\n```lua\n{\n    \"OXY2DEV/ui.nvim\",\n    lazy = false\n};\n```\n\nFor `plugins/ui.lua` users,\n\n```lua\nreturn {\n    \"OXY2DEV/ui.nvim\",\n    lazy = false\n};\n```\n\n### 🦠 Mini.deps\n\n```lua\nlocal MiniDeps = require(\"mini.deps\");\n\nMiniDeps.add({\n    source = \"OXY2DEV/ui.nvim\"\n});\n```\n\n### 🌒 Rocks.nvim\n\n\u003e[!WARNING]\n\u003e `luarocks package` may sometimes be a bit behind `main`.\n\n```vim\n:Rocks install ui.nvim\n```\n\n## 🔩 Configuration\n\nThe plugin can be configured via the `setup()` function. You can check the default configuration table [here](https://github.com/OXY2DEV/ui.nvim/blob/752ef3a1eb2aa2ffa33efd055f3cbbc6b417b435/lua/ui/spec.lua#L5-L1172).\n\nA simplified version of the configuration table is given below,\n\n```lua\nrequire(\"ui\").setup({\n    popupmenu = {\n        enable = true,\n\n        winconfig = {},\n        tooltip = nil,\n\n        styles = {\n            default = {\n                padding_left = \" \",\n                padding_right = \" \",\n\n                icon = nil,\n                text = nil,\n\n                normal_hl = nil,\n                select_hl = \"CursorLine\",\n                icon_hl = nil\n            },\n\n            example = {\n                condition = function ()\n                    return true;\n                end,\n\n                icon = \"I \"\n            }\n        }\n    },\n\n    cmdline = {\n        enable = true,\n\n        styles = {\n            default = {\n                cursor = \"Cursor\",\n                filetype = \"vim\",\n\n                icon = { { \"I \", \"@comment\" } },\n                offset = 0,\n\n                title = nil,\n                winhl = \"\"\n            },\n\n            example = {\n                condition = function ()\n                    return true;\n                end,\n\n                cursor = \"@comment\"\n            }\n        }\n    },\n\n    message = {\n        enable = true,\n\n        message_winconfig = {},\n        list_winconfig = {},\n        confirm_winconfig = {},\n        history_winconfig = {},\n\n        ignore = function ()\n            return false:\n        end,\n\n        showcmd = {\n            max_width = 10,\n            modifier = nil\n        },\n\n        msg_styles = {\n            default = {\n                duration = 500,\n\n                modifier = nil,\n                decorations = {\n                    icon = { { \"I \" } }\n                }\n            },\n\n            example = {\n                condition = function ()\n                    return true;\n                end,\n\n                decorations = {\n                    icon = { { \"B \" } }\n                }\n            }\n        },\n\n        is_list = function ()\n            return false;\n        end,\n\n        list_styles = {\n            default = {\n                modifier = nil,\n\n                row = nil,\n                col = nil,\n\n                width = nil,\n                height = nil,\n\n                winhl = nil\n            },\n\n            example = {\n                condition = function ()\n                    return true;\n                end,\n\n                border = \"rounded\"\n            }\n        },\n        confirm_styles = {\n            default = {\n                modifier = nil,\n\n                row = nil,\n                col = nil,\n\n                width = nil,\n                height = nil,\n\n                winhl = nil\n            },\n\n            example = {\n                condition = function ()\n                    return true;\n                end,\n\n                border = \"rounded\"\n            }\n        }\n    }\n});\n```\n\n\u003e[!TIP]\n\u003e You can call the `setup()` as many times as you want!\n\n------\n\nThe various configurations tables are given below. You can find them in `spec.default` [here](https://github.com/OXY2DEV/ui.nvim/blob/main/lua/ui/spec.lua).\n\n### ✨ Command-line\n\nCommand-line styles can be found in `spec.default.cmdline.styles`. These are,\n\n- `__keymap`, used for showing keys \u0026 actions in confirmation messages.\n- `search_up`, used for `/`.\n- `search_down`, used for `?`.\n- `set`, used for `:set`.\n- `shell`, used for `:!`.\n- `substitute`, used for `:s/`, `:%s/`, `:1,2s/` etc.\n- `lua_eval`, used for `:=`.\n- `lua`, used for `:lua`.\n- `prompt`, used when a prompt is shown.\n\n### ✨ Message\n\nMessage styles can be found in `spec.default.message.msg_styles`. These are,\n\n- `__swap`, Used for the swapfile exists error.\n- `__spell`, Used when adding new entries to the spell file(e.g. `zg`).\n- `__lua_error`, Used for error messages in Lua.\n- `option`, Used for the output of `:set \u003coption\u003e?`, this sometimes picks up normal messages too.\n- `search`, Used for showing searched word,\n- `error_msg`, Used for regular error messages(fallback for `__lua_error`).\n- `highlight_link`, Used for output of `:hi \u003cgroup\u003e` that uses `link`.\n- `highlight_group`, Used for output of `:hi \u003cgroup\u003e`.\n- `write`, Used for the message shown when writing to a file.\n- `undo_redo`, Used for `undo` \u0026 `redo` messages.\n\n#### Confirm messages\n\nConfirm message styles can be found in `spec.default.message.confirm_styles`. These are,\n\n- `swap_alert`, Used when showing the `swapfile exists` error.\n- `write_confirm`, Used when writing a read-only file.\n\n#### List messages\n\nList message styles can be found in `spec.default.message.list_styles`. These are,\n\n- `ls`, Used for the buffer list.\n- `hi`, Used for the output of `:hi`.\n\n### ✨ Pop-up menu\n\nPop-up menu item styles can be found in `spec.default.popupmenu.styles`. These are,\n\n- `buffer_variable`, Used for buffer local variables(`b:*`).\n- `global_variable`, Used for global variables(`g:*`).\n- `local_variable`, Used by `l:*`, `a:*` \u0026 `s:*`.\n- `tabpage_variable`, Used for tabpage local variables(`t:*`).\n- `vim_variable`, Used for Vim variables(`v:`).\n- `window_variable`, Used for window local variables(`w:`).\n- `class`, Used for items whose kind is `m`.\n- `function`, Self-explanatory.\n- `macro`, Used for items whose kind is `d`.\n- `type_definition`, Used for items whose kind is `t`.\n- `variable`, Used for items whose kind is `v`.\n\n## 💻 Commands\n\nYou can run `:UI` to toggle the custom UI. It has the following sub-commands,\n\n- `enable`\n  Enables custom UI.\n\n- `disable`\n  Disables custom UI.\n\n- `toggle`\n  Toggles custom UI.\n\n- `clear`\n  Clears all visible messages.\n\n## 🎨 Highlight groups\n\nBy default this plugin comes with the following highlight groups,\n\n- `UICmdlineDefault`\n- `UICmdlineDefaultIcon`\n- `UICmdlineLua`\n- `UICmdlineLuaIcon`\n- `UICmdlineEval`\n- `UICmdlineEvalIcon`\n- `UICmdlineSearchUp`\n- `UICmdlineSearchUpIcon`\n- `UICmdlineSearchDown`\n- `UICmdlineSearchDownIcon`\n- `UICmdlineSubstitute`\n- `UICmdlineSubstituteIcon`\n\n- `UIMessageDefault`\n- `UIMessageOk`\n- `UIMessageInfo`\n- `UIMessageInfoSign`\n- `UIMessageWarn`\n- `UIMessageWarnSign`\n- `UIMessageError`\n- `UIMessageErrorSign`\n- `UIMessagePalette`\n- `UIMessageErrorSign`\n\n- `UIHistoryKeymap`\n- `UIHistoryDesc`\n- `UIMenuSelect`\n- `UIMenuKeymap`\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxy2dev%2Fui.nvim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxy2dev%2Fui.nvim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxy2dev%2Fui.nvim/lists"}