ui.nvim · View & render · vimdoc

:help ui

Statusline, tabline and theme layer for Neovim

doc/ui.txt — rendered from the plugin's own vimdoc

*ui.txt*  Statusline, tabline and theme layer for Neovim

Author:  Stefan Bartl
License: MIT

CONTENTS *ui-contents*

    1. Introduction ........................ |ui-introduction|
    2. Requirements ........................ |ui-requirements|
    3. Setup ............................... |ui-setup|
    4. Commands ............................ |ui-commands|
    5. Keymaps ............................. |ui-keymaps|
    6. Statusline variants ................. |ui-variants|
    7. Tabline styles ....................... |ui-tabline-styles|
    8. Health .............................. |ui-health|

1. INTRODUCTION *ui-introduction*

ui.nvim is the frame around the window: statusline, tabline and theme
assembly.

The dividing line this plugin draws is worth stating plainly:

    Content lives inside the window. ui.nvim paints the frame around it.

Cursorline, mode tinting, indent guides and occurrence highlighting are
content; they work with any statusline and are out of scope here. Statusline,
tabline and theme assembly are frame.

2. REQUIREMENTS *ui-requirements*

    Neovim      0.11+
    lib.nvim    required
    NvChad      not required by this plugin's own code (v2.5, if present)

As of roadmap step 6, this plugin's own code no longer needs NvChad OR base46
to load, assemble, render, move buffers and tabs, or switch themes:
ui.statusline.render is the vim.o.statusline / generate() walk that
used to be entirely nvchad.init + nvchad.stl.utils.generate() (step 4;
step 3 had already ported the primitives and separator reads that walk
itself uses), ui.bindings.keymaps.tabufline.state is the vim.t.bufs
bookkeeping and close_buffer()/move_buf() that used to be entirely
nvchad/tabufline/lazyload.lua + nvchad.tabufline (step 5), and
ui.theme.palette/ui.theme.transparency/ui.bindings.usrcmds.themes
replace base46 (step 6): accent colors come from the active colorscheme's
own highlight groups, transparency is this plugin's own toggle, and theme
switching is a real :colorscheme call. Verified headless, with neither
NvChad nor base46 on the runtimepath: all four statusline presets assemble
and render end to end, buffer/tab navigation works against real buffers and
tabs, and theme/transparency switching works against a real colorscheme.

As of roadmap step 7 (2026-09-13), that is also true of a real install: the
reference host this plugin was extracted from calls `ui.statusline.render
.enable()` from its own startup, and NvChad is not installed there any more
at all. This plugin covers statusline/tabline/theme only, though -- it does
not replace whatever else a distribution bundle also installed (Mason,
which-key, Treesitter, Telescope, and so on all needed their own separate
plugin specs in that host once NvChad's own bundle stopped providing them).

Soft, each blanking only its own statusline segment: nvim-web-devicons,
gitsigns.nvim, casedesk.nvim, filetree.nvim, github_stats.nvim,
runtime-analysis.nvim, recommender.nvim, sessions.nvim, sandbox.nvim,
lazy.nvim. :checkhealth ui reports each of them separately; the full
table with links is docs/requirements.md.

3. SETUP *ui-setup*

Two entry points, at different times.

ui.config.setup() runs from your own config's startup, whenever you want
the frame drawn -- no distribution hook needed or expected. It only
assembles a config table; enable() on each renderer is the separate step
that actually points vim.o.statusline/vim.o.tabline at it:
    -- Anywhere in your own startup, once (the reference host's own shape,
    -- config/ui_statusline/init.lua -- adapt names, not structure):
    local ok, assembled = pcall(require("ui.config").setup, {
      theme = { theme_toggle = { "rosepine", "tokyonight" } },
    })
    if ok then
      require("ui.statusline.render").enable(assembled.ui.statusline)
      require("ui.tabline.render").enable(assembled.ui.tabline)
    end
ui.setup(opts) runs afterwards, from your own config, and answers "which
keymaps and commands exist":
    require("ui").setup({ all = true })
Nothing is on by default -- the two halves are independently useful, so the
flags are explicit:
    require("ui").setup({ usrcmds = true })  -- commands only, no keymaps
    all       (boolean) shorthand for every flag below
    keymaps   (boolean) buffer/tab navigation and tabline mappings
    usrcmds   (boolean) the :UI command and theme management

Theme overrides go to ui.config.setup, not here:
    require("ui.config").setup({
      theme = { theme_toggle = { "rosepine", "tokyonight" }, transparency = true },
    })

4. COMMANDS *ui-commands*

                                                                       *:UI*
One verb with subcommands; <Tab> completes the subcommand and, where it takes
one, its argument. A bare :UI opens the option float. docs/BINDINGS.md has
the long form of each row.

                                                                 *:UI-theme*
:UI theme [{name}]
    Switch to a colorscheme (:colorscheme {name}); without {name}, show the
    current one. {name} completes over every colorscheme Neovim can see,
    read at the moment <Tab> is pressed. :Theme [{name}] is a shortcut.

                                                                *:UI-themes*
:UI themes
    List available themes, marking the active one.

                                                                *:UI-picker*
:UI picker
    Open a floating theme picker (this plugin's own ui.kit.select): the
    highlighted theme applies live as the cursor moves over the list, <CR>
    keeps it, <Esc>/q/closing the float any other way restores whatever
    theme was active before the picker opened.

                                                                *:UI-toggle*
:UI toggle
    Swap between the two themes in theme.theme_toggle.

                                                          *:UI-transparency*
:UI transparency [on|off]
    Toggle background transparency, or set it.

                                                             *:UI-screenkey*
:UI screenkey [on|off]
    Toggle the keystroke HUD (ui.screenkey), for recording demos. Off by
    default. Keys typed into a secret prompt, input()/inputsecret(), a
    buftype=prompt buffer or a buffer listed in setup({ hide }) are never
    shown.

                                                  *:UI-sticky* *:UI-context*
:UI sticky [{action} [{a} [{b}]]]
:UI context ...
    The sticky code context (ui.context): the enclosing function, class or
    loop lines (in Markdown the heading chain) pinned over the window's first
    rows. Without {action} it toggles. {action} is one of on, off,
    toggle, status, depth [1-6|all], lines [{filetype}] [{n}],
    reset or up [{n}] (jump to the n-th enclosing scope). context is
    the older name of the same command.

                                                                 *:UI-color*
:UI color [{#rrggbb}]
    Open the colour picker (ui.colorpicker), optionally on a start colour.
    <CR> writes the pick back over the literal it opened on, y yanks.

                                                                   *:UI-zen*
:UI zen [on|off]
    Toggle the zen box (ui.zen): the current buffer alone in a centred
    float over a dimmed backdrop; closing the float restores everything.

                                                               *:UI-winpick*
:UI winpick
    Pick a window by letter (ui.windowpicker) and jump to it.

                                                                *:UI-notify*
:UI notify [on|off|history|clear]
    Toggle ui.notify (vim.notify as level-coloured toasts), open the
    recorded history, or forget it. Off by default.

                                                                  *:UI-keys*
:UI keys [{prefix}]
    List the mappings under {prefix} (default <leader>) as a menu
    (ui.keys); picking a row runs the mapping.

                                                               *:UI-variant*
:UI variant [{name}]
    Switch the active statusline preset at runtime; without {name}, open a
    choice with the current one marked. {name} completes over the variant
    registry (see |ui-variants| below): the four shipped presets, plus
    anything a host registered under its own name.

                                                              *:UI-variants*
:UI variants
    List registered variants, marking the active one.

                                                         *:UI-tabline-style*
:UI tabline-style [{name}]
    Switch the active tabline chip-boundary look at runtime; without {name},
    open a choice with the current one marked (an error instead while the
    tabline is not enabled). {name} completes over the tabline-style
    registry (see |ui-tabline-styles| below): the shipped looks, plus
    anything a host registered under its own name.

                                                        *:UI-tabline-styles*
:UI tabline-styles
    List registered tabline styles, marking the active one.

                                                            *:UI-kit-preset*
:UI kit-preset [{name}]
    Switch the preset (border and colours) every ui.kit popup and toast
    resolves through; without {name}, open a choice with the current one
    marked. A preset name that is also a tabline style switches the tabline
    style too.

                                                           *:UI-kit-presets*
:UI kit-presets
    List the registered kit presets, marking the active one.

                                                        *:UI-kit-playground*
:UI kit-playground [{demo}]
    Open the kit playground: a list of demos, one per ui.kit primitive
    (popups, dialogs, lists, chips, toasts, history, progress and the
    :KitPreview editor). The preview pane says what the highlighted demo
    shows and which keys to try; <CR> or 1-9 start one, and a dialog's
    answer is shown in a toast. With {demo} (completes over the ids),
    start that demo directly. Demo code only: no global setting changes.

                                                               *:UI-modules*
:UI modules
    List every catalogued statusline segment (built into the "default"
    theme, or a standalone module), what each shows, what it needs, and
    which shipped presets already use it. Same data as docs/modules.md.

                                                              *:UI-progress*
:UI progress
    Popup list of what lib.nvim.progress is tracking right now (the same
    registry the plugin_progress segment renders).

                                                                *:UI-status*
:UI status
    Current theme, transparency state, statusline variant and tabline
    style.

                                                                 *:UI-slots*
:UI slots
    List the numbered action slots (see docs/BINDINGS.md).

:UI slots toggle
:UI slots open
:UI slots close
    The slot bar: a chip per slot at the right edge (number, icon, label).
    A click runs the slot, a right click offers apply, edit, copy and clear
    (and, for a file, open in a split, vsplit or tab), the wheel over the bar
    scrolls it. With more slots than rows it scrolls like
    an accordion (the top one drops out, the next comes in below) and keeps
    the slot you applied last, or the one of the current file, in sight;
    "▲ +n" and "▼ +n" say what is hidden. The option show = true opens it
    when the slots are switched on.

:UI slots panel
    The slot panel: a window docked at the edge, one row per slot, the cursor is
    the selection. <CR> runs the slot, typing a number goes to that slot (1,
    then 2 for slot 12), e edits it, a adds one, dd clears it, y copies what it stands for,
    K shows a preview of it beside the panel (a file: its lines up to
    preview.max_kb/preview.max_lines, at the position it was last left
    at; an address: its host, or with preview.fetch = true (off by
    default: it is a request to that host) its page as hover.nvim shows it,
    "loading ..." first;
    preview.mode = "auto" opens it by itself (the preview of the row you
    start on is there at once; preview.delay ms is how long the cursor must
    rest before it follows to another row), "off" switches it off),
    <C-j>/<C-k> move it down/up, a right click opens a menu (apply, edit, copy,
    open a file in a split, vsplit or tab, clear), q or <Esc> closes. Leaving
    the panel closes it.

:UI slots edit [{n}]
    Add a slot in the editor (a chooser for the kind, then a sheet with its
    fields), or change slot {n}. Only the kinds a data file may hold are made
    here; a cmd or lua slot, and a slot fixed in setup(), are not changed.

:UI slots {n}
    Run slot {n}: open its file or address, copy its text, ...

:UI slots add [{n}]
    Put the current file into the next free slot, or into slot {n}
    when that one is free.

:UI slots yank {n}
    Copy what slot {n} stands for (its path, address or text).

:UI slots clear {n}|all
    Empty a slot, or every slot that is not fixed in setup().

:UI slots move {from} {to}
    Move a slot to another number; the two swap when {to} is taken.

:UI slots kinds
    List the kinds a slot can be.

                                                                  *:UI-help*
:UI help
    The subcommand list, printed; generated from the same routes as the
    option float (a bare :UI opens the float).

No subcommand takes a range or a count: each acts on global state, where
neither has a meaning.

5. KEYMAPS *ui-keymaps*

Registered by ui.setup({ keymaps = true }).

    <Tab>          next buffer
    <S-Tab>        previous buffer
    <leader>bc     close the current buffer (or {count} of them), keeping
                   the window layout -- an uncounted close flashes the chip
                   first; {count} > 1 closes immediately, unflashed
    <leader>bq     close every listed buffer in the current tab -- all
                   flash together first, then close as one batch

    <leader>tr     move the current buffer right in the tabline
    <leader>tl     move it left
    <leader>tt     move the current buffer into a new tab

    <leader>ut     toggle between the two themes in theme.theme_toggle
    <leader>uP     open the visual theme picker (live preview)

Every one is wrapped: a failure notifies and returns rather than raising,
because these sit on keys pressed constantly and a traceback out of <Tab>
makes the editor feel broken.

<leader>tr and <leader>tl go through ui.bindings.keymaps.tabufline.state
(own code, step 5, not nvchad.tabufline) -- they work with NvChad entirely
absent.

                                                          *ui-tabline-mouse*

Tabline mouse

The tabline's own click protocol reports the button, so these are not
keymaps and need no keymaps = true:

    left click     switch to the chip's buffer
    left drag      carry the chip along the bar; it re-slots live
    right click    that tab's context menu (also on a chip's "x")
    middle click   close the chip
    click on "x"   close the chip

The tab menu (ui.tabline.menu) holds only actions on that tab: Save
(modified only), Close, Close others / to the left / to the right / saved,
Move to position... (3 absolute, +2/-1 relative), Move left / right /
to start / to end, Copy path, Open in split / vertical split, Move to new tab
page. context_menu, drag and middle_click_close on the tabline config
each turn one gesture off (back to a plain switch).

min_contrast (default 4.5) on the tabline config lifts the foreground of the
inactive chips toward Normal's foreground when the scheme's TabLine colors
do not reach that WCAG contrast (symbols: 3 at most); false turns it off.

A host's own global <RightMouse> mapping keeps working if it replays the
native click (normal! <RightMouse>) and then returns when
require("ui.tabline.menu").pointer_on_tabline() is true. See
docs/BINDINGS.md for the snippet.

6. STATUSLINE VARIANTS *ui-variants*

Four generic presets ship. Which one is assembled at boot is the
STATUSLINE_VARIANT constant in lua/ui/config/init.lua -- but since this
plugin owns its own render entrypoint (step 4), that is no longer the only
chance: :UI variant {name} switches it at runtime.

    default   full-featured, closest to the historical NvChad default
    minimal   cursor, working directory, progress -- nothing else
    lsp       LSP-aware breadcrumbs plus the enhanced segments
    blocks    "lsp"'s segments, drawn as gen_block chips

An unknown name falls back to default with a notification rather than
throwing. |:checkhealth| reports the boot-time default, whether it is
registered, and the actually active one (ui.config.get_variant())
separately -- they can differ after a runtime switch.

This used to be six presets; custom (personal-plugin-coupled: casedesk.nvim,
filetree.nvim) moved to docs/examples/personal-statusline-example.lua instead
of staying a shipped preset, and lspbased/custom_light (the same segment
set assembled two different ways) became one file, lsp.

ui.config.variants is the registry both the four shipped presets and any
host-registered variant live in -- what :UI variant's completion and
ui.config.setup({ variant = "name" }) both read:
    require("ui.config.variants").register("personal", require("your_config.statusline"))
    require("ui.config").setup({ variant = "personal" })
opts.variant also still accepts a table directly, used anonymously without
a name to register:
    require("ui.config").setup({
      variant = require("your_config.statusline"),
    })

7. TABLINE STYLES *ui-tabline-styles*

Unlike a statusline variant (a whole {order, modules} table), the tabline
has one shipped config -- cfg.style is a single field of it, picking the
chip-boundary look between buffer chips:

    rounded_chip  (default) a cap on every internal boundary; square only
                  where the visible run actually meets an edge
    chip          nothing added; chips sit flush against each other
    divider       one plain vertical bar per internal boundary, no rounding

The older names rounded (= rounded_chip) and square (= chip) stay
registered as aliases; hacker is the flush look again, under the name of
the ui.kit.theme preset, so :UI kit-preset hacker switches the tabline
too. An unrecognized or unset name falls back to rounded_chip rather than
throwing.

ui.tabline.styles is the registry both the three shipped looks and any
host-registered style live in -- what :UI tabline-style's completion
reads, and what cfg.style resolves through on every redraw:
    local styles = require("ui.tabline.styles")
    styles.register("my_style", function(chips, chip_bufs, cur, flush_right)
      -- mutate `chips` in place; see ui.tabline.styles's own doc comment
      -- for what each parameter is
    end)
    require("ui.config").setup({ tabline = { style = "my_style" } })
:UI tabline-style {name} switches it at runtime without a full
ui.config.setup() round-trip: it mutates cfg.style on the already-`
enable()d tabline config directly, then :redrawtabline` makes it visible.

A style is ONE named choice; a decorator is a post-pass on top of whichever
style is active -- how a host marks chips (a group colour, an underline)
without replacing the user's look:
    local styles = require("ui.tabline.styles")
    styles.add_decorator("my_marks", function(chips, chip_bufs, cur, flush_right)
      -- same arguments as a style, runs after it on every redraw; may
      -- rewrite chips[i], must not change a chip's display width
    end)
    styles.remove_decorator("my_marks")
Decorators run in name order, each isolated by pcall.

User UiTablineReordered (data = { bufnr = <moved buffer> }) fires after
a user-level move (drag, "move to position", pin/unpin, the swap keymaps)
has written the new order to vim.t.bufs. A host that keeps its own
ordering invariant re-establishes it from a handler -- by writing
vim.t.bufs directly, not by calling a mover back.

8. HEALTH *ui-health*

    :checkhealth ui
Eight sections: dependencies (lib.nvim required; NvChad presence reported as
information, not a dependency check, since step 4; nvchad.tabufline gone
from this list entirely at step 5, base46/base46.themes gone the same way
at step 6), this plugin's own statusline render entrypoint (resolves?
renders the "default" theme's fallback modules without NvChad?), the tabline
render entrypoint (same shape, one option later), the assembled
configuration, which submodules setup() turned on (buffer/tab navigation
included, under keymaps), the soft dependencies each statusline segment
needs, whether ui.winbar resolves for a content plugin to contribute its
breadcrumb line to, and which optional integrations currently resolve.

That last section lists the foreign modules this plugin probes (see
ui.util.soft_require). A missing one is never an error -- standalone is
the ordinary case and the matching segment renders empty by design -- but
the list is printed because a soft dependency that disappears upstream
otherwise disables a feature in complete silence.

The dependency section returns early only if lib.nvim itself is missing or
incomplete -- everything below it needs lib.nvim, and a missing NvChad no
longer stops the report (it stopped being fatal at step 4).

RIGHT-CLICK MENU *ui-menu*

ui.setup({ menu = { ... } }) (or require("ui.menu").setup()) binds
<RightMouse> (menu at the pointer); key = "<A-b>" adds the same menu at the
cursor. Off until asked for. It shows a fly-out per installed sister plugin, the general sections
Code / Clipboard / File / Delete / Tools, and rows of your own (extra).

A sister plugin appears when it is installed, menu.integrations.<name> is not
false, and the plugin has not switched itself off (its submenu() returns nil;
the recommended switch name is integrations.ui_menu = false). Delete All / Delete File are off unless enabled in
menu.entries. "Copy/Delete Marked" act on the Visual selection captured when
the menu opened. See lua/ui/menu/README.md.