📚 Guide: UI

[!NOTE] This is still considered experimental, so some behavior may change in the future.

This wiki will be valid for the main(current 0.11) branch of Neovim.

Neovim's UI can be modified using Lua via the vim.ui_attach() function. See :h vim.ui_attach().

You typically start with something like this,

---@type integer Namespace for the UI(s).
local namespace = vim.api.nvim_create_namespace("ui");

vim.ui_attach(namespace, {
    ext_messages = true,
    -- ext_cmdline = true
}, function (event, ...)
    --- {event}, Event name
    --- {...}, Arguments this event produces.
    --- Do stuff...
end);

Of course, by itself this doesn't do much. But this allows you to do various things based on the value of event.

And, if you ever want to revert to the original UI. You can simply do it via vim.ui_detach(). See :h vim.ui_detach().

vim.ui_detach(namespace);

[!TIP] I recommend you checkout :h ui.txt before progressing further.

This page explains how the ui.lua file works.

📚 Toggling custom UI

[!TIP] You can check the value of ui.enabled to see if the UI is attached or not!

The custom UI can be enabled by triggering the attach() function. This function triggers vim.ui_attach()(see :h vim.ui_attach()) and redirects UI events to the various sub-modules.

A map is used to determine where an event should go to.

You can visualize how events are handled like so,

vim.ui_attach() --> event_map ==> handle() ==> ...

You can also detach the plugin from the UI at any time by calling the detach() function. This will trigger vim.ui_detach()(see :h vim.ui_detach()) which will detach the plugin from the UI.

📚 Handling errors

To prevent internal errors from affecting Neovim, the function calls for the UI are wrapped in pcall().

-- ❌ Bad
some_function();

-- ✅ Good
pcall(some_function);