petertriho/nvim-scrollbar

github github
scrollingscrollbar
stars 1,076
issues 3
subscribers 7
forks 25
CREATED

UPDATED


The default scrollbar and minimap while scrolling past diagnostics, Git hunks, and search matches

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.

Jump and Glance

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.

Label mode: labels on the scrollbar marks, a peek float from an uppercase label, and a jump

The glance window: a list of the marks, a preview that follows the selection, an edit in the preview, and a jump

Hover: the peek float opens while the pointer rests on a mark of the scrollbar

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.

Requirements

Installation

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.

lazy.nvim:

{
    "petertriho/nvim-scrollbar",
    opts = {},
}

With opts = {}, lazy.nvim calls require("scrollbar").setup({}). Put any configuration overrides inside opts.

vim-plug:

Plug 'petertriho/nvim-scrollbar'

With vim-plug or another manual installation, configure the plugin from Lua:

require("scrollbar").setup()

Quick Start

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.

Minimap

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.

Pickers and Floats

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:

  • The list and the preview of the snacks.nvim picker
  • The results and the preview of the Telescope picker

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.

Providers

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.

Documentation

Guides

  • Configuration: defaults, providers, exclusions, mark types, layout lanes, text functions and recipes, profiles, precedence, and validation
  • Presets: the twelve scrollbar presets, the eight minimap presets, and their precedence
  • Visibility: source-window visibility, autohide, hide-on-cursor behavior, commands, and Lua APIs
  • Floats: scrollbars and minimaps on the windows of the snacks.nvim and Telescope pickers and on other floats
  • Layout and geometry: layout lanes, placement, line and screen-line units, and wide scrollbars
  • Mouse: clicks, mark navigation, thumb dragging, and focus behavior
  • Jump and Glance: label mode, the peek float, the glance pickers, and hover
  • Highlights: generated groups, direct definitions, blending, and manual highlights
  • Migration: changes required from earlier releases
  • Development: tests, quality checks, benchmarks, and CI

Provider Guides

Minimap Guides

License

MIT