Configuration

You can configure the scrollbar by passing a table to the setup function. Below are the default values and explanations for the available options.

Default Configuration

require("scrollbar").setup({
    show = true,
    show_in_active_only = false,
    set_highlights = true,
    folds = 1000, -- handle folds, set to number to disable folds if no. of lines in buffer exceeds this
    max_lines = false, -- disables if no. of lines in buffer exceeds this
    hide_if_all_visible = false, -- Hides everything if all lines are visible
    throttle_ms = 100,
    handle = {
        text = " ",
        blend = 30, -- Integer between 0 and 100. 0 for fully opaque and 100 to full transparent. Defaults to 30.
        color = nil,
        color_nr = nil, -- cterm
        highlight = "CursorColumn",
        hide_if_all_visible = true, -- Hides handle if all lines are visible
    },
    marks = {
        Cursor = {
            text = "•",
            priority = 0,
            highlight = "Normal",
        },
        Search = {
            text = { "-", "=" },
            priority = 1,
            highlight = "Search",
        },
        Error = {
            text = { "-", "=" },
            priority = 2,
            highlight = "DiagnosticVirtualTextError",
        },
        Warn = {
            text = { "-", "=" },
            priority = 3,
            highlight = "DiagnosticVirtualTextWarn",
        },
        Info = {
            text = { "-", "=" },
            priority = 4,
            highlight = "DiagnosticVirtualTextInfo",
        },
        Hint = {
            text = { "-", "=" },
            priority = 5,
            highlight = "DiagnosticVirtualTextHint",
        },
        Misc = {
            text = { "-", "=" },
            priority = 6,
            highlight = "Normal",
        },
        GitAdd = {
            text = "┆",
            priority = 7,
            highlight = "GitSignsAdd",
        },
        GitChange = {
            text = "┆",
            priority = 7,
            highlight = "GitSignsChange",
        },
        GitDelete = {
            text = "▁",
            priority = 7,
            highlight = "GitSignsDelete",
        },
    },
    excluded_buftypes = {
        "terminal",
    },
    excluded_filetypes = {
        "blink-cmp-menu",
        "dropbar_menu",
        "dropbar_menu_fzf",
        "DressingInput",
        "cmp_docs",
        "cmp_menu",
        "noice",
        "prompt",
        "TelescopePrompt",
    },
    autocmd = {
        render = {
            "BufWinEnter",
            "TabEnter",
            "TermEnter",
            "WinEnter",
            "CmdwinLeave",
            "TextChanged",
            "VimResized",
            "WinScrolled",
        },
        clear = {
            "BufWinLeave",
            "TabLeave",
            "TermLeave",
            "WinLeave",
        },
    },
    handlers = {
        cursor = true,
        diagnostic = true,
        gitsigns = false, -- Requires gitsigns
        handle = true,
        search = false, -- Requires hlslens
        ale = false, -- Requires ALE
    },
})

Key Options

• folds: Controls fold handling. Set to a number (e.g., 1000) to disable fold calculation if the buffer lines exceed this number. This helps performance on massive files.
• max_lines: If false, the scrollbar is always shown. If set to a number, the scrollbar will be disabled for buffers larger than this limit.
• throttle_ms: Time in milliseconds to throttle the render function. Higher values improve performance but reduce responsiveness.
• handle: Configuration for the main scrollbar handle (the bar moving up and down).
  • blend: Transparency (0-100).
  • hide_if_all_visible: Auto-hides the handle if the entire buffer fits on screen.
• marks: Configuration for specific indicators (Search, Git, Diagnostics). You can change the text, priority (layering), and highlight group here.
• handlers: Boolean flags to enable/disable specific integrations.

Exclusions

You can prevent the scrollbar from appearing in specific environments using:

• excluded_buftypes: e.g., terminals.
• excluded_filetypes: e.g., Telescope prompts, completion menus.