nvim-scrollbar shows one floating scrollbar for each source window. Each
split window gets its own thumb. The scrollbar has typed mark lanes, optional
screen-line positions that follow wraps and folds, and mouse navigation. An
optional floating minimap shows a compressed view of the buffer, with a
viewport tint, a cursor accent, provider marks, and mouse navigation. Label
mode, a peek float, and glance pickers take you to the marks and show their
lines.
Label mode puts a label on each mark of the scrollbar. Type a label to move to
the mark, or type the uppercase label to see the lines of the mark in a peek
float first. Glance shows a list of the marks in the glance window, which has
a preview pane, or in a snacks.nvim, Telescope, or custom picker. With
scrollbar.hover, the peek float also opens when the mouse pointer stays
on a mark. Label mode is inspired by
flash.nvim, and the glance window by
glance.nvim.
vim.keymap.set("n", "<leader>j", function()
require("scrollbar").jump()
end, { desc = "Jump to a scrollbar mark" })
vim.keymap.set("n", "<leader>g", function()
require("scrollbar").glance()
end, { desc = "Glance at the marks" })
The commands are :ScrollbarJump [types] and :ScrollbarGlance [types]. See
Jump and Glance.
mouse option must enable the modes that
you want, for example set mouse=a. The plugin never changes mouse.If you upgrade from v1, read the migration guide first.
If you are not ready to migrate, pin the v1 branch, for example
{ "petertriho/nvim-scrollbar", branch = "v1" } with lazy.nvim.
{
"petertriho/nvim-scrollbar",
opts = {},
}
With opts = {}, lazy.nvim calls require("scrollbar").setup({}). Put any
configuration overrides inside opts.
Plug 'petertriho/nvim-scrollbar'
With vim-plug or another manual installation, configure the plugin from Lua:
require("scrollbar").setup()
By default, the cursor, diagnostic, search, and named-mark providers are enabled for every eligible source window. A small custom setup can look like this:
require("scrollbar").setup({
providers = {
search = { incsearch = true },
marks = { numbers = true },
},
scrollbar = {
preset = "zed",
autohide = true,
},
})
This example enables autohide. The scrollbars start concealed. Cursor movement or scrolling in a source window reveals the scrollbar of that window.
The built-in scrollbar presets are vscode, zed, intellij, minimal,
review, search, navigate, gvim, eclipse, sublime, emacs, and
xcode. The showcase
has a screenshot and the setup of every scrollbar preset and minimap preset.
An ordered list of profiles can select a different appearance for each source window:
require("scrollbar").setup({
scrollbar = {
preset = "zed",
profiles = {
{
match = { filetypes = { "markdown", "text" } },
preset = "minimal",
},
{
match = { filetypes = { "lua" } },
preset = "review",
},
},
},
})
The plugin uses the first profile that matches. Profiles change only appearance
options. Providers, exclusions, visibility, autohide, and max_lines are
global.
Setup rejects unknown keys and invalid values. See the configuration reference for every default and accepted value.
The minimap is disabled by default. It has its own configuration block,
profiles, mouse handling, and commands. It does not show, hide, or move the
scrollbar. Both renderers share the top-level providers, marks, and
exclude tables.
require("scrollbar").setup({
minimap = {
enabled = true,
},
})
By default, each source window gets a 16-column minimap at its north-east
corner, beside the scrollbar. The minimap draws the text as Braille dots, with
one source line in each row of dots, and it scrolls with the source window.
scale = "fit" shows the whole buffer instead, and encoding = "block" draws
█ cells. Treesitter colors the dots by default when the buffer has a parser.
LSP semantic-token colors are an opt-in provider:
require("scrollbar").setup({
providers = {
lsp_semantic_tokens = true,
},
minimap = {
enabled = true,
},
})
The minimap has eight presets: vscode, sublime, zed, xcode,
overview, compact, minimal, and blocks. A minimap preset is separate
from the scrollbar preset:
require("scrollbar").setup({
scrollbar = { preset = "zed" },
minimap = {
enabled = true,
preset = "zed",
},
})
Provider marks, such as diagnostics, search matches, and Git hunks, tint the
occupied cells of their row. minimap.marks changes the priority or the
highlight of a mark type for the minimap. The value false hides a type:
require("scrollbar").setup({
minimap = {
enabled = true,
marks = {
Search = { priority = 0, highlight = "IncSearch" },
Hint = false,
},
},
})
minimap.blend sets the blend of the full float. minimap.background_blend
sets the blend of only the base surface. See
Minimap configuration. By default, the
minimap of the active source window hides while the editing cursor is inside
the minimap.
The automatic highlight groups of the minimap have their own public names,
such as ScrollbarMinimapSearch. Setup keeps your existing definitions of the
public scrollbar and minimap groups.
See the minimap documentation for the map, placement, marks, and mouse behavior.
By default, the scrollbar and the minimap show only on normal windows. With
floats = true in its block, the scrollbar or the minimap also shows on these
floats:
A when function selects other floats:
require("scrollbar").setup({
scrollbar = {
floats = {
snacks = true,
telescope = true,
when = require("scrollbar.recipes").when.filetypes({ "lazy" }),
},
},
})
A bar on a float uses the z-index of that float + 1. A click or a drag on the bar of the snacks list selects an item. See Floats.
| Provider | Scrollbar | Minimap | Source | Dependency |
|---|---|---|---|---|
cursor |
on | on | Source-window cursor | None |
diagnostic |
on | on | Neovim vim.diagnostic |
None |
search |
on | on | Native / and ? search |
None |
marks |
on | on | Letter marks, and optional numbered marks | None |
gitsigns |
off | off | Git hunks | gitsigns.nvim |
mini_diff |
off | off | mini.diff hunks | mini.diff |
signify |
off | off | vim-signify hunks | vim-signify |
vgit |
off | off | vgit hunks | vgit.nvim |
ale |
off | off | ALE location list | ALE |
coc |
off | off | Coc diagnostic list | coc.nvim |
qflist |
off | off | Quickfix list | None |
loclist |
off | off | Location list of each window | None |
treesitter |
unavailable | on | Treesitter highlight captures | Installed parser |
lsp_semantic_tokens |
unavailable | off | LSP semantic tokens | Attached LSP client |
Configure the providers in the top-level providers table. A provider value is
false, true, or a table of options. In a table, the scrollbar and
minimap flags select the renderers that show the provider. Each built-in
provider runs once, and only when an enabled renderer uses it.
See the provider overview for the shared rules, dependencies, update behavior, and links to every provider. To add a new data source, use the custom provider API.