dropbar.nvim

IDE-like breadcrumbs, out of the box

A polished, IDE-like, highly-customizable winbar for Neovim
with drop-down menu support and multiple backends

• Features and TODOs
• Requirements
• Installation
• Usage
  • Usage with vim.ui.select
• Configuration
  • Options
  • General
  • Icons
  • Symbol
  • Bar
  • Menu
  • Fzf
  • Sources
    • Path
    • Treesitter
    • LSP
    • Markdown
    • Terminal
  • API
  • Utility Functions
  • Bar Utility Functions
  • Menu Utility Functions
  • Highlighting
• Developers
  • Architecture
  • Classes
  • dropbar_t
  • dropbar_symbol_t
  • dropbar_menu_t
  • dropbar_menu_entry_t
  • dropbar_menu_hl_info_t
  • dropbar_source_t
  • dropbar_select_opts_t
  • Making a New Source
  • Making a Source With Drop-Down Menus
  • Default on_click() Callback
  • Lazy-Loading Expensive Fields
  • Practical Examples
    • Highlight File Name Using Custom Highlight Group DropBarFileName
• Similar Projects

Features and TODOs

https://github.com/Bekaboo/dropbar.nvim/assets/76579810/e8c1ac26-0321-4762-9975-b20fc3098c5a

• [x] Opening drop-down menus or go to definition with a single mouse click

  

• [x] Pick mode for quickly selecting a component in the winbar with shortcuts

  

• [x] Automatically truncating long components

  

  • [x] Better truncation when winbar is still too long after shortening all components

• [x] Multiple backends that support fall-backs

  dropbar.nvim comes with five builtin sources:

  • [x] lsp: gets symbols from language servers using nvim's builtin LSP framework

  • [x] markdown: a custom incremental parser that gets symbol information about markdown headings

  • [x] path: gets current file path

  • [x] treesitter: gets symbols from treesitter parsers using nvim's builtin treesitter integration

  • [x] terminal: easily switch terminal buffers using the dropdown menu

  To make a new source yourself, see making a new source.

  For source fall-backs support, see bar options.

• [x] Zero config & Zero dependency

  dropbar.nvim does not require nvim-lspconfig, nvim-treesitter or any third-party UI libraries to work. As long as the language server or the treesitter parser is installed, it should work just fine.

  Optionally, you can install telescope-fzf-native to add fuzzy search support to dropbar menus.

• [x] Drop-down menu components and winbar symbols that response to mouse/cursor hovering:

  

  • This features requires :h mousemoveevent to be enabled.

• [x] Preview symbols in their source windows when hovering over them in the drop-down menu

  

• [x] Reorient the source window on previewing or after jumping to a symbol

• [x] Add scrollbar to the menu when the symbol list is too long

  

• [x] Background color support* thanks @theofabilous

  

  • This is currently an experimental feature that is only available in branch feat-winbar-background-highlight.
  • To achieve the same effect in branch master, see discussions in #2

• [ ] Add preview for symbols shown in the winbar

• [ ] Preview symbols (files) from path source

• [ ] Support visual mode selection to select/delete multiple symbols

• [ ] Ability to hide/show the winbar on each window separately

• [ ] Add more tests for the sources path, lsp, and treesitter

• [ ] Configurable scrollbar appearance

• [ ] Update winbar sources dynamically

• [ ] More responsive mouse clicking & hovering in insert (fzf) mode, like in normal mode

Requirements

• Neovim >= 0.10.0
• Optional
  • nvim-web-devicons, if you want to see icons for different filetypes
  • telescope-fzf-native, if you want fuzzy search support
  • Working language server installation for the lsp source to work
  • Working treesitter parser installation for the treesitter source to work

Installation

• Using lazy.nvim

  require('lazy').setup({
  {
    'Bekaboo/dropbar.nvim',
    -- optional, but required for fuzzy finder support
    dependencies = {
      'nvim-telescope/telescope-fzf-native.nvim'
    }
  }
  })

• Using packer.nvim

  require('packer').startup(function(use)
  use({
    'Bekaboo/dropbar.nvim',
    requires = {
      'nvim-telescope/telescope-fzf-native.nvim'
    }
  })
  end)

• Using native package manager

  mkdir -p ~/.local/share/nvim/site/pack/packages/
  git clone https://github.com/Bekaboo/dropbar.nvim ~/.local/share/nvim/site/pack/packages/start/dropbar.nvim

  Lazy-loading is unneeded as it is already done in plugin/dropbar.lua.

Usage

• Basics
  • Moves the cursor around and see the winbar reflects your current context
• Mouse support
  • Click on a component in the winbar to open a drop-down menu of its siblings
  • Click on an entry in the drop-down menu to go to its location
  • Click on the indicator in the drop-down menu to open a sub-menu of its children
• Pick mode
  • Use require('dropbar.api').pick() to enter interactive pick mode or require('dropbar.api').pick(<idx>) to directly select a component at idx.
  • Inside interactive pick mode, press the corresponding pivot shown before each component to select it
• Fuzzy finder
  • Use dropbar_menu_t:fuzzy_find_open() to interactively filter, select and preview entries using fzf
  • <Esc>: exit fzf mode
  • <Up>/<Down>: move the cursor in fzf mode
  • <CR>: call the on_click callback of the symbol under the cursor
• Default keymaps in drop-down menu
  • <LeftMouse>: call the on_click callback of the symbol at the mouse click
  • <CR>: find the first clickable symbol in the current drop-down menu entry and call its on_click callback
  • i: enter fzf mode from the menu
  • q / <Esc>: close current menu
  • To disable, remap or add new keymaps in the drop-down menu, see menu options

Usage with vim.ui.select

Dropbar can be used as a drop-in replacement for Neovim's builtin vim.ui.select menu.

To enable this functionality, simply replace vim.ui.select with dropbar.utils.menu.select:

vim.ui.select = require('dropbar.utils.menu').select

Configuration

Options

General

These options live under opts.general and are used to configure the general behavior of the plugin:

• opts.general.enable: boolean|fun(buf: integer, win: integer): boolean
  • Controls whether to enable the plugin for the current buffer and window
  • If a function is provided, it will be called with the current bufnr and winid and should return a boolean
  • Default:

    function(buf, win, _)
    return vim.api.nvim_buf_is_valid(buf)
    and vim.api.nvim_win_is_valid(win)
    and vim.wo[win].winbar == ''
    and vim.fn.win_gettype(win) == ''
    and vim.bo[buf].ft ~= 'help'
    and ((pcall(vim.treesitter.get_parser, buf)) and true or false)
    end,

• opts.general.attach_events: string[]
  • Controls when to evaluate the enable() function and attach the plugin to corresponding buffer or window
  • Default:

    {
    'OptionSet',
    'BufWinEnter',
    'BufWritePost',
    }

• opts.general.update_interval: number
  • Wait for a short time before updating the winbar, if another update request is received within this time, the previous request will be cancelled, this improves the performance when the user is holding down a key (e.g. 'j') to scroll the window
  • If you encounter performance issues when scrolling the window, try setting this option to a number slightly larger than 1000 / key_repeat_rate
  • Default: 0
• opts.general.update_events.win: string[]
  • List of events that should trigger an update on the dropbar attached to a single window
  • Default:

    {
    'CursorMoved',
    'CursorMovedI',
    'WinEnter',
    'WinResized',
    }

• opts.general.update_events.buf: string[]
  • List of events that should trigger an update on all dropbars attached to a buffer
  • Default:

    {
    'BufModifiedSet',
    'FileChangedShellPost',
    'TextChanged',
    'TextChangedI',
    }

• opts.general.update_events.global: string[]
  • List of events that should trigger an update of all dropbars in current nvim session
  • Default:

    {
    'DirChanged',
    'VimResized',
    }

Icons

These options live under opts.icons and are used to configure the icons used by the plugin:

• opts.icons.enable: boolean
  • Whether to enable icons
  • Default: true
• opts.icons.kinds.use_devicons: boolean
  • Whether to use nvim-web-devicons to show icons for different filetypes
  • Default: true
• opts.icons.kinds.symbols: table<string, string>
  • Table mapping the different kinds of symbols to their corresponding icons
  • Default:

    {
    Array = '󰅪 ',
    Boolean = ' ',
    BreakStatement = '󰙧 ',
    Call = '󰃷 ',
    CaseStatement = '󱃙 ',
    Class = ' ',
    Color = '󰏘 ',
    Constant = '󰏿 ',
    Constructor = ' ',
    ContinueStatement = '→ ',
    Copilot = ' ',
    Declaration = '󰙠 ',
    Delete = '󰩺 ',
    DoStatement = '󰑖 ',
    Enum = ' ',
    EnumMember = ' ',
    Event = ' ',
    Field = ' ',
    File = '󰈔 ',
    Folder = '󰉋 ',
    ForStatement = '󰑖 ',
    Function = '󰊕 ',
    H1Marker = '󰉫 ', -- Used by markdown treesitter parser
    H2Marker = '󰉬 ',
    H3Marker = '󰉭 ',
    H4Marker = '󰉮 ',
    H5Marker = '󰉯 ',
    H6Marker = '󰉰 ',
    Identifier = '󰀫 ',
    IfStatement = '󰇉 ',
    Interface = ' ',
    Keyword = '󰌋 ',
    List = '󰅪 ',
    Log = '󰦪 ',
    Lsp = ' ',
    Macro = '󰁌 ',
    MarkdownH1 = '󰉫 ', -- Used by builtin markdown source
    MarkdownH2 = '󰉬 ',
    MarkdownH3 = '󰉭 ',
    MarkdownH4 = '󰉮 ',
    MarkdownH5 = '󰉯 ',
    MarkdownH6 = '󰉰 ',
    Method = '󰆧 ',
    Module = '󰏗 ',
    Namespace = '󰅩 ',
    Null = '󰢤 ',
    Number = '󰎠 ',
    Object = '󰅩 ',
    Operator = '󰆕 ',
    Package = '󰆦 ',
    Pair = '󰅪 ',
    Property = ' ',
    Reference = '󰦾 ',
    Regex = ' ',
    Repeat = '󰑖 ',
    Scope = '󰅩 ',
    Snippet = '󰩫 ',
    Specifier = '󰦪 ',
    Statement = '󰅩 ',
    String = '󰉾 ',
    Struct = ' ',
    SwitchStatement = '󰺟 ',
    Terminal = ' ',
    Text = ' ',
    Type = ' ',
    TypeParameter = '󰆩 ',
    Unit = ' ',
    Value = '󰎠 ',
    Variable = '󰀫 ',
    WhileStatement = '󰑖 ',
    }

• opts.icons.ui.bar: table<string, string>
  • Controls the icons used in the winbar UI
  • Default:

    {
    separator = ' ',
    extends = '…',
    }

• opts.icons.ui.menu: table<string, string>
  • Controls the icons used in the menu UI
  • Default:

    {
    separator = ' ',
    indicator = ' ',
    }

    Symbol

These options live under opts.symbol and are used to control the behavior of the symbols:

• opts.symbol.preview.reorient: fun(win: integer, range: {start: {line: integer, character: integer}, end: {line: integer, character: integer}})
  • Function to reorient the source window when previewing symbol given the source window win and the range of the symbol range
  • Default:

    function(_, range)
    local invisible = range['end'].line - vim.fn.line('w$') + 1
    if invisible > 0 then
    local view = vim.fn.winsaveview() --[[@as vim.fn.winrestview.dict]]
    view.topline = math.min(
      view.topline + invisible,
      math.max(1, range.start.line - vim.wo.scrolloff + 1)
    )
    vim.fn.winrestview(view)
    end
    end

• opts.symbol.jump.reorient: fun(win: integer, range: {start: {line: integer, character: integer}, end: {line: integer, character: integer}})
  • Function to reorient the source window after jumping to symbol given the source window win and the range of the symbol range
  • Default:

    function(win, range)
    local view = vim.fn.winsaveview()
    local win_height = vim.api.nvim_win_get_height(win)
    local topline = range.start.line - math.floor(win_height / 4)
    if
    topline > view.topline
    and topline + win_height < vim.fn.line('$')
    then
    view.topline = topline
    vim.fn.winrestview(view)
    end
    end

Bar

These options live under opts.bar and are used to control the behavior of the winbar:

• opts.bar.hover: boolean
  • Whether to highlight the symbol under the cursor
  • This feature requires 'mousemoveevent' to be enabled
  • Default: true
• opts.bar.sources: dropbar_source_t[]|fun(buf: integer, win: integer): dropbar_source_t[]
  • List of sources to show in the winbar
  • If a function is provided, it will be called with the current bufnr and winid and should return a list of sources
  • Default:

    function(buf, _)
    local sources = require('dropbar.sources')
    local utils = require('dropbar.utils')
    if vim.bo[buf].ft == 'markdown' then
    return {
      sources.path,
      sources.markdown,
    }
    end
    if vim.bo[buf].buftype == 'terminal' then
    return {
      sources.terminal,
    }
    end
    return {
    sources.path,
    utils.source.fallback({
      sources.lsp,
      sources.treesitter,
    }),
    }
    end

  • For more information about sources, see dropbar_source_t.
• opts.bar.padding: { left: number, right: number }
  • Padding to use between the winbar and the window border
  • Default: { left = 1, right = 1 }
• opts.bar.pick.pivots: string
  • Pivots to use in pick mode
  • Default: 'abcdefghijklmnopqrstuvwxyz'
• opts.bar.truncate: boolean
  • Whether to truncate the winbar if it doesn't fit in the window
  • Default: true

Menu

These options live under opts.menu and are used to control the behavior of the menu:

• opts.menu.quick_navigation: boolean

  • When on, automatically set the cursor to the closest previous/next clickable component in the direction of cursor movement on CursorMoved
  • Default: true

• opts.menu.entry.padding: { left: number, right: number }

  • Padding to use between the menu entry and the menu border
  • Default: { left = 1, right = 1 }

• opts.menu.preview: boolean

  • Whether to enable previewing for menu entries
  • Default: true

• opts.menu.keymaps: table<string, function|string|table<string, function>|table<string, string>>

  • Buffer-local keymaps in the menu
  • Use <key> = <function|string> to map a key in normal mode in the menu buffer, or use <key> = table<mode, function|string> to map a key in specific modes.
  • Default:

    {
    ['q'] = '<C-w>q',
    ['<Esc>'] = '<C-w>q',
    ['<LeftMouse>'] = function()
    local menu = utils.menu.get_current()
    if not menu then
      return
    end
    local mouse = vim.fn.getmousepos()
    local clicked_menu = utils.menu.get({ win = mouse.winid })
    -- If clicked on a menu, invoke the corresponding click action,
    -- else close all menus and set the cursor to the clicked window
    if clicked_menu then
      clicked_menu:click_at({ mouse.line, mouse.column - 1 }, nil, 1, 'l')
      return
    end
    utils.menu.exec('close')
    utils.bar.exec('update_current_context_hl')
    if vim.api.nvim_win_is_valid(mouse.winid) then
      vim.api.nvim_set_current_win(mouse.winid)
    end
    end,
    ['<CR>'] = function()
    local menu = utils.menu.get_current()
    if not menu then
      return
    end
    local cursor = vim.api.nvim_win_get_cursor(menu.win)
    local component = menu.entries[cursor[1]]:first_clickable(cursor[2])
    if component then
      menu:click_on(component, nil, 1, 'l')
    end
    end,
    ['<MouseMove>'] = function()
    local menu = utils.menu.get_current()
    if not menu then
      return
    end
    local mouse = vim.fn.getmousepos()
    utils.menu.update_hover_hl(mouse)
    if M.opts.menu.preview then
      utils.menu.update_preview(mouse)
    end
    end,
    ['i'] = function()
    local menu = utils.menu.get_current()
    if not menu then
      return
    end
    menu:fuzzy_find_open()
    end,
    },

• opts.menu.scrollbar: table<string, boolean>

  • Scrollbar configuration for the menu.
  • Default:

    {
    enable = true,
    -- if false, only the scrollbar thumb will be shown
    background = true
    }

• opts.menu.win_configs: table<string, dropbar_menu_win_config_opts_t>

  • Window configurations for the menu, see :h nvim_open_win()
  • Each config key in opts.menu.win_configs accepts either a plain value which will be passes directly to nvim_open_win(), or a function that takes the current menu (see dropbar_menu_t) as an argument and returns a value to be passed to nvim_open_win().
  • Default:

    {
    border = 'none',
    style = 'minimal',
    row = function(menu)
    return menu.prev_menu
        and menu.prev_menu.clicked_at
        and menu.prev_menu.clicked_at[1] - vim.fn.line('w0')
      or 0
    end,
    ---@param menu dropbar_menu_t
    col = function(menu)
    if menu.prev_menu then
      return menu.prev_menu._win_configs.width
        + (menu.prev_menu.scrollbar and 1 or 0)
    end
    local mouse = vim.fn.getmousepos()
    local bar = require('dropbar.api').get_dropbar(
      vim.api.nvim_win_get_buf(menu.prev_win),
      menu.prev_win
    )
    if not bar then
      return mouse.wincol
    end
    local _, range = bar:get_component_at(math.max(0, mouse.wincol - 1))
    return range and range.start or mouse.wincol
    end,
    relative = 'win',
    win = function(menu)
    return menu.prev_menu and menu.prev_menu.win
      or vim.fn.getmousepos().winid
    end,
    height = function(menu)
    return math.max(
      1,
      math.min(
        #menu.entries,
        vim.go.pumheight ~= 0 and vim.go.pumheight
          or math.ceil(vim.go.lines / 4)
      )
    )
    end,
    width = function(menu)
    local min_width = vim.go.pumwidth ~= 0 and vim.go.pumwidth or 8
    if vim.tbl_isempty(menu.entries) then
      return min_width
    end
    return math.max(
      min_width,
      math.max(unpack(vim.tbl_map(function(entry)
        return entry:displaywidth()
      end, menu.entries)))
    )
    end,
    zindex = function(menu)
    if menu.prev_menu then
      if menu.prev_menu.scrollbar and menu.prev_menu.scrollbar.thumb then
        return vim.api.nvim_win_get_config(menu.prev_menu.scrollbar.thumb).zindex
      end
      return vim.api.nvim_win_get_config(menu.prev_win).zindex
    end
    end,
    }

Fzf

These options live under opts.fzf and are used to control the behavior and appearance of the fuzzy finder interface.

• opts.fzf.keymaps

  • The keymaps that will apply in insert mode, in the fzf prompt buffer
  • Same config as opts.menu.keymaps
  • Default:

    keymaps = {
    ['<LeftMouse>'] = function()
    ---@type dropbar_menu_t
    local menu = utils.menu.get_current()
    if not menu then
      return
    end
    local mouse = vim.fn.getmousepos()
    if not mouse then
      return
    end
    if mouse.winid ~= menu.win then
      local default_func = M.opts.menu.keymaps['<LeftMouse>']
      if type(default_func) == 'function' then
        default_func()
      end
      menu:fuzzy_find_close(false)
      return
    elseif mouse.winrow > vim.api.nvim_buf_line_count(menu.buf) then
      return
    end
    vim.api.nvim_win_set_cursor(menu.win, { mouse.line, mouse.column - 1 })
    menu:fuzzy_find_click_on_entry(function(entry)
      return entry:get_component_at(mouse.column - 1, true)
    end)
    end,
    ['<MouseMove>'] = function()
    ---@type dropbar_menu_t
    local menu = utils.menu.get_current()
    if not menu then
      return
    end
    local mouse = vim.fn.getmousepos()
    if not mouse then
      return
    end
    -- If mouse is not in the menu window or on the border, end preview
    -- and clear hover highlights
    if
      mouse.winid ~= menu.win
      or mouse.line <= 0
      or mouse.column <= 0
      or mouse.winrow > #menu.entries
    then
      -- Find the root menu
      while menu and menu.prev_menu do
        menu = menu.prev_menu
      end
      if menu then
        menu:finish_preview(true)
        menu:update_hover_hl()
      end
      return
    end
    if M.opts.menu.preview then
      menu:preview_symbol_at({ mouse.line, mouse.column - 1 }, true)
    end
    menu:update_hover_hl({ mouse.line, mouse.column - 1 })
    end,
    ['<Up>'] = api.fuzzy_find_prev,
    ['<Down>'] = api.fuzzy_find_next,
    ['<C-k>'] = api.fuzzy_find_prev,
    ['<C-j>'] = api.fuzzy_find_next,
    ['<C-p>'] = api.fuzzy_find_prev,
    ['<C-n>'] = api.fuzzy_find_next,
    ['<CR>'] = api.fuzzy_find_click,
    ['<S-Enter>'] = function()
    api.fuzzy_find_click(-1)
    end,
    }

• opts.fzf.win_configs

  • Options passed to :h nvim_open_win. The fuzzy finder will use its parent window's config by default, but options set here will override those.
  • Same config as opts.menu.win_configs

  • Default:

    win_configs = {
    relative = 'win',
    anchor = 'NW',
    height = 1,
    win = function(menu)
    return menu.win
    end,
    width = function(menu)
    local function border_width(border)
      if type(border) == 'string' then
        if border == 'none' or border == 'shadow' then
          return 0
        end
        return 2 -- left and right border
      end
    
      local left, right = 1, 1
      if
        (#border == 1 and border[1] == '')
        or (#border == 4 and border[4] == '')
        or (#border == 8 and border[8] == '')
      then
        left = 0
      end
      if
        (#border == 1 and border[1] == '')
        or (#border == 4 and border[4] == '')
        or (#border == 8 and border[4] == '')
      then
        right = 0
      end
      return left + right
    end
    local menu_width = menu._win_configs.width
      + border_width(menu._win_configs.border)
    local self_width = menu._win_configs.width
    local self_border = border_width(
      (
        M.opts.fzf.win_configs
        and M.eval(M.opts.fzf.win_configs.border, menu)
      )
        or (menu.fzf_win_configs and M.eval(
          menu.fzf_win_configs.border,
          menu
        ))
        or menu._win_configs.border
    )
    
    if self_width + self_border > menu_width then
      return self_width - self_border
    else
      return menu_width - self_border
    end
    end,
    row = function(menu)
    local menu_border = menu._win_configs.border
    if
      type(menu_border) == 'string'
      and menu_border ~= 'shadow'
      and menu_border ~= 'none'
    then
      return menu._win_configs.height + 1
    elseif menu_border == 'none' then
      return menu._win_configs.height
    end
    local len_menu_border = #menu_border
    if
      len_menu_border == 1 and menu_border[1] ~= ''
      or (len_menu_border == 2 or len_menu_border == 4) and menu_border[2] ~= ''
      or len_menu_border == 8 and menu_border[8] ~= ''
    then
      return menu._win_configs.height + 1
    else
      return menu._win_configs.height
    end
    end,
    col = function(menu)
    local menu_border = menu._win_configs.border
    if
      type(menu_border) == 'string'
      and menu_border ~= 'shadow'
      and menu_border ~= 'none'
    then
      return -1
    end
    if
      type(menu_border) == 'table' and menu_border[#menu_border] ~= ''
    then
      return -1
    end
    return 0
    end,
    },

• opts.fzf.prompt

  • Prompt string that will be displayed in the statuscolumn of the fzf input window.
  • Can include highlight groups
  • Default:

    prompt = '%#htmlTag# '

• opts.fzf.char_pattern

  • Default:

    char_pattern = '[%w%p]'

• opts.fzf.retain_inner_spaces

  • Default:

    retain_inner_spaces = true

• opts.fzf.fuzzy_find_on_click

  • When opening an entry with a submenu via the fuzzy finder, open the submenu in fuzzy finder mode.
  • Default:

    fuzzy_find_on_click = true

Sources

These options live under opts.sources and are used to control the behavior of each sources.

Path

• opts.sources.path.relative_to: string|fun(buf: integer, win: integer): string
  • The path to use as the root of the relative path
  • If a function is provided, it will be called with the current buffer number and window id as arguments and should return a string to be used as the root of the relative path
  • Notice: currently does not support .. relative paths
  • Default:

    function(_, win)
    -- Workaround for Vim:E5002: Cannot find window number
    local ok, cwd = pcall(vim.fn.getcwd, win)
    return ok and cwd or vim.fn.getcwd()
    end

• opts.sources.path.filter: function(name: string): boolean
  • A function that takes a file name and returns whether to include it in the results shown in the drop-down menu
  • Default:

    function(_)
    return true
    end

• opts.sources.path.modified: function(sym: dropbar_symbol_t): dropbar_symbol_t
  • A function that takes the last symbol_{dropbar_symbol_t} in the result got from the path source and returns an alternative symbol_{dropbar_symbol_t} to show if the current buffer is modified
  • Default:

    function(sym)
    return sym
    end

  • To set a different icon, name, or highlights when the buffer is modified, you can change the corresponding fields in the returned symbol_{dropbar_symbol_t}

    function(sym)
    return sym:merge({
    name = sym.name .. '[+]',
    icon = ' ',
    name_hl = 'DiffAdded',
    icon_hl = 'DiffAdded',
    -- ...
    })
    end

• opts.sources.path.preview: boolean|fun(path: string): boolean?|nil
  • A boolean or a function that takes a file path and returns whether to preview the file under cursor
  • Default:

    function(path)
    local stat = vim.uv.fs_stat(path)
    if not stat or stat.type ~= 'file' then
    return false
    end
    if stat.size > 524288 then
    vim.notify(
      string.format(
        '[dropbar.nvim] file "%s" too large to preview',
        path
      ),
      vim.log.levels.WARN
    )
    return false
    end
    return true
    end,

Treesitter

• opts.sources.treesitter.name_regex: string
  • Vim regex used to extract a short name from the node text
  • Default: [=[[#~!@\*&.]*[[:keyword:]]\+!\?\(\(\(->\)\+\|-\+\|\.\+\|:\+\|\s\+\)\?[#~!@\*&.]*[[:keyword:]]\+!\?\)*]=]
• opts.sources.treesitter.valid_types: string[]
  • A list of treesitter node types to include in the results
  • Default:

    {
    'array',
    'boolean',
    'break_statement',
    'call',
    'case_statement',
    'class',
    'constant',
    'constructor',
    'continue_statement',
    'delete',
    'do_statement',
    'element',
    'enum',
    'enum_member',
    'event',
    'for_statement',
    'function',
    'h1_marker',
    'h2_marker',
    'h3_marker',
    'h4_marker',
    'h5_marker',
    'h6_marker',
    'if_statement',
    'interface',
    'keyword',
    'macro',
    'method',
    'module',
    'namespace',
    'null',
    'number',
    'operator',
    'package',
    'pair',
    'property',
    'reference',
    'repeat',
    'rule_set',
    'scope',
    'specifier',
    'struct',
    'switch_statement',
    'type',
    'type_parameter',
    'unit',
    'value',
    'variable',
    'while_statement',
    'declaration',
    'field',
    'identifier',
    'object',
    'statement',
    }

LSP

• opts.sources.lsp.request.ttl_init: number
  • Number of times to retry a request before giving up
  • Default: 60
• opts.sources.lsp.request.interval: number
  • Number of milliseconds to wait between retries
  • Default: 1000

Markdown

• opts.sources.markdown.parse.look_ahead: number
  • Number of lines to update when cursor moves out of the parsed range
  • Default: 200

Terminal

Thanks @willothy for implementing this.

• opts.sources.terminal.icon: string or fun(buf: integer): string

  • Icon to show before terminal names
  • Default:

    icon = function(buf)
    local icon = M.opts.icons.kinds.symbols.Terminal
    if M.opts.icons.kinds.use_devicons then
    icon = require('nvim-web-devicons').get_icon_by_filetype(
      vim.bo[buf].filetype
    ) or icon
    end
    return icon
    end

• opts.sources.terminal.name: string or fun(buf: integer): string

  • Easy to integrate with other plugins (for example, toggleterm.nvim):

    name = function(buf)
    local name = vim.api.nvim_buf_get_name(buf)
    -- the second result val is the terminal object
    local term = select(2, require("toggleterm.terminal").indentify(name))
    if term then
    return term.display_name or term.name
    else
    return name
    end
    end

  • Default: vim.api.nvim_buf_get_name

• opts.sources.terminal.show_current: boolean

  • Show the current terminal buffer in the menu
  • Default: true

API

dropbar.nvim exposes a few functions in lua/dropbar/api.lua that can be used to interact with the winbar or the drop-down menu:

• get_dropbar(buf: integer?, win: integer): dropbar_t? prefer utils.bar.get()
  • Get the dropbar associated with the given buffer and window
  • For more information about the dropbar_t type, see dropbar_t
• get_current_dropbar(): dropbar_t? prefer utils.bar.get_current()
  • Get the dropbar associated with the current buffer and window
• get_dropbar_menu(win: integer): dropbar_menu_t? prefer utils.menu.get()
  • Get the drop-down menu associated with the given window
  • For more information about the dropbar_menu_t type, see dropbar_menu_t
• get_current_dropbr_menu(): dropbar_menu_t? prefer utils.menu.get_current()
  • Get the drop-down menu associated with the current window
• goto_context_start(count: integer?)
  • Move the cursor to the start of the current context
  • If count is 0 or nil, go to the start of current context, or the start at previous context if cursor is already at the start of current context
  • If count is positive, goto the start of count previous context
• select_next_context()
  • Open the menu of current context to select the next context
• pick(idx: integer?)
  • Pick a component from current winbar
  • If idx is nil, enter interactive pick mode to select a component
  • If idx is a number, directly pick the component at that index if it exists
• fuzzy_find_toggle(opts: table?)
  • Toggle the fuzzy finder interface for the current dropbar menu
  • Options override the default / config options for the fuzzy finder
• fuzzy_find_click(component: number | (fun(entry: dropbar_menu_entry_t):dropbar_sumbol_t)?)
  • If component is a number, the component-nth symbol is selected, unless 0 or -1 is supplied, in which case the first or last clickable component is selected, respectively.
  • If it is a function, it receives the dropbar_menu_entry_t as an argument and should return the dropbar_symbol_t that is to be clicked.
• fuzzy_find_navigate(direction: 'up'|'down'|integer)
  • Navigate to the nth previous/next entry while fuzzy finding
• fuzzy_find_prev()
  • Navigate to the previous entry while fuzzy finding
• fuzzy_find_next()
  • Navigate to the next entry while fuzzy finding

Utility Functions

Here are some utility functions that can be handy when writing your customize your config:

Bar Utility Functions

Defined in lua/dropbar/utils/bar.lua.

• utils.bar.get(opts?): (dropbar_t?)|table<integer, dropbar_t>|table<integer, table<integer, dropbar_t>>
  • Get the dropbar(s) associated with the given buffer and window
  • If only opts.win is specified, return the dropbar attached the window;
  • If only opts.buf is specified, return all dropbars attached the buffer;
  • If both opts.win and opts.buf are specified, return the dropbar attached the window that contains the buffer;
  • If neither opts.win nor opts.buf is specified, return all dropbars in the form of table<buf, table<win, dropbar_t>>
• utils.bar.get_current(): dropbar_t?
  • Get the dropbar associated with the current buffer and window

Menu Utility Functions

Defined in lua/dropbar/utils/menu.lua.

• utils.menu.get(opts): (dropbar_menu_t?)|table<integer, dropbar_menu_t>
  • Get dropbar menu
  • If opts.win is specified, return the dropbar menu attached the window;
  • If opts.win is not specified, return all opened dropbar menus
• utils.menu.get_current(): dropbar_menu_t?
  • Get current dropbar menu
• utils.menu.select(items: any[], opts: table, on_choice: function(item, idx))
  • Opt-in replacement for vim.ui.select
  • Supports non-string items by formatting via the opts.format_item callback

Highlighting

dropbar.nvim defines the following highlight groups that, override them in your colorscheme to change the appearance of the drop-down menu, the names should be self-explanatory:

Developers

Architecture

                                              ┌──────────────────┐
                                              │winbar at win 1000│ {k}th symbol clicked
                                              │ contaning buf 1  ├──────────────────────┐
                                              └───────┬─▲────────┘                      │
                                                      ▼ │                               │
                                          _G.dropbar.get_dropbar_str()                  │
                                                      │ ▲                               │
    ┌──────────────┐                           ┌──────▼─┴──────┐                        │
    │sources       │                           │_G.dropbar.bars│                        │
    │ ┌───┐        │                           └──────┬─▲──────┘                        │
    │ │lsp│        │                       ┌───────┬──▼─┴──┬───────┐                    │
    │ └───┘        │                     ┌─▼─┐   ┌─┴─┐   ┌─┴─┐    ...                   │
    │ ┌──────────┐ │                     │[1]│   │[2]│   │[3]│                          │
    │ │treesitter│ │                     └─┬─┘   └─┬─┘   └─┬─┘                          │
    │ └──────────┘ │                       │      ...     ...                           │
    │  ...         │                       └──┬─▲─────────────┬──────┐                  │
    └─────┬─▲──────┘                        ┌─▼─┴──┐       ┌──┴───┐ ...                 │
          │ │                               │[1000]│       │[1015]│                     │
          │ │                               └─┬─▲──┘       └──────┘                     │
          │ │                    __tostring() │ │ return string cache                   │
          │ │                             ┌───▼─┴───┐                    ┌──────────────▼──────────────┐
          │ │                             │dropbar_t├────────────────────▶     _G.dropbar.callbacks    │
          │ │    On update events         └───┬─▲───┘  register symbol   └──────────────┬──────────────┘
          │ │ get_symbols(1, 1000, <cursor>)  │ │    on_click() callbacks               │
          │ └─────────────────────────────────┘ │                       ┌──────────┬────▼─────┬─────────┐
          └─────────────────────────────────────┘                   ┌───▼────┐ ┌───┴────┐ ┌───┴────┐   ...
      each source returns dropbar_symbol_t[]                        │['buf1']│ │['buf2']│ │['buf3']│
     dropbar_t adds symbols as its components                       └───┬────┘ └───┬────┘ └───┬────┘
          dropbar_t flushes string cache                                │         ...        ...
                                                                        └────────┬───────────────┬─────────┐
                                                                           ┌─────▼─────┐   ┌─────┴─────┐  ...
                                                                           │['win1000']│   │['win1015']│
                                                                           └─────┬─────┘   └─────┬─────┘
                                                                                 │              ...
                                                                  ┌─────────┬────▼────┬─────────┐
                                                              ┌───┴───┐    ...   ┌────┴────┐   ...
                                                              │['fn1']│          │['fn{k}']│
                                                              └───────┘          └────┬────┘
                                                                                      ▼
                                                      invoke _G.dropbar.bars[1][1000].components[k]:on_click()
                                                                                      │
                                                                                      ▼
                                                                     open drop-down menu, goto symbol, etc

Classes

dropbar_t

Declared and defined in lua/dropbar/bar.lua.

dropbar_t is a class that represents a winbar.

It gets symbols_{dropbar_symbol_t[]} from sources_{dropbar_source_t} and renders them to a string. It is also responsible for registering on_click callbacks of each symbol in the global table _G.dropbar.callbacks so that nvim knows which function to call when a symbol is clicked.

dropbar_t has the following fields:

dropbar_t has the following methods:

dropbar_symbol_t

Declared and defined in lua/dropbar/bar.lua.

dropbar_symbol_t is a class that represents a symbol in a dropbar. It is the basic element of dropbar_t and dropbar_menu_entry_t.

dropbar_symbol_t has the following fields:

dropbar_symbol_t has the following methods:

dropbar_menu_t

Declared and defined in lua/dropbar/menu.lua.

dropbar_menu_t is a class that represents a drop-down menu.

dropbar_menu_t has the following fields:

dropbar_menu_t has the following methods:

dropbar_menu_entry_t

Declared and defined in lua/dropbar/menu.lua.

dropbar_menu_entry_t is a class that represents an entry (row) in a drop-down menu. A dropbar_menu_t instance is made up of multiple dropbar_menu_entry_t instances while a dropbar_menu_entry_t instance can contain multiple dropbar_symbol_t instances.

dropbar_menu_entry_t has the following fields:

dropbar_menu_entry_t has the following methods:

dropbar_menu_hl_info_t

Declared and defined in lua/dropbar/menu.lua.

dropbar_menu_hl_info_t is a class that represents a highlight range in a single line of a drop-down menu.

dropbar_menu_hl_info_t has the following fields:

dropbar_source_t

Declared in lua/dropbar/sources/init.lua.

dropbar_source_t is a class that represents a source of a drop-down menu.

dropbar_source_t has the following field:

dropbar_select_opts_t

Declared in lua/dropbar/utils/menu.lua.

dropbar_select_opts_t is a class that represents the options passed to utils.menu.select (vim.ui.select with some extensions).

dropbar_select_opts_t has the following fields:

Making a New Source

A dropbar_source_t instance is just a table with get_symbols field set to a function that returns an array of dropbar_symbol_t instances given the buffer number, the window id, and the cursor position.

We have seen a simple example of a custom source in the default config of opts.bar.sources where the second source is set to a combination of lsp/treesitter/markdown sources using the utils.source.fallback() factory function, which simply returns a table containing a get_symbols() function where each source passed to utils.source.fallback() is queried and the first non-empty result get from the sources is returned as the result of the combined source.

Here is another example of a custom source that will always return two symbols saying 'Hello' and 'dropbar' with highlights 'hl-Keyword' and 'hl-Title' and a smiling face shown in 'hl-WarningMsg' at the start of the first symbol; clicking on the first symbol will show a notification message saying 'Have you smiled today?', followed by the smiling face icon used in the in dropbar symbol:

local bar = require('dropbar.bar')
local custom_source = {
  get_symbols = function(_, _, _)
    return {
      bar.dropbar_symbol_t:new({
        icon = ' ',
        icon_hl = 'WarningMsg',
        name = 'Hello',
        name_hl = 'Keyword',
        on_click = function(self)
          vim.notify('Have you smiled today? ' .. self.icon)
        end,
      }),
      bar.dropbar_symbol_t:new({
        name = 'dropbar',
        name_hl = 'Title',
      }),
    }
  end,
}

Add this source to opts.bar.sources table to see it in action:

require('dropbar').setup({
  bar = {
    sources = {
      custom_source,
    },
  },
})

Making a Source With Drop-Down Menus

The following example shows how to make a source that returns two symbols with the first symbol having a drop-down menu with a single entry saying 'World':

local bar = require('dropbar.bar')
local menu = require('dropbar.menu')
local custom_source = {
  get_symbols = function(_, _, _)
    return {
      bar.dropbar_symbol_t:new({
        icon = ' ',
        icon_hl = 'WarningMsg',
        name = 'Hello',
        name_hl = 'Keyword',
        on_click = function(self)
          self.menu = menu.dropbar_menu_t:new({
            entries = {
              menu.dropbar_menu_entry_t:new({
                components = {
                  bar.dropbar_symbol_t:new({
                    icon = ' ',
                    icon_hl = 'WarningMsg',
                    name = 'World',
                    name_hl = 'Keyword',
                    on_click = function(sym)
                      vim.notify('Have you smiled today? ' .. sym.icon)
                    end,
                  }),
                },
              }),
            },
          })
          self.menu:toggle()
        end,
      }),
      bar.dropbar_symbol_t:new({
        name = 'dropbar',
        icon = ' ',
        name_hl = 'Special',
        icon_hl = 'Error',
      }),
    }
  end,
}

Default on_click() Callback

dropbar_symbol_t:new() defines a default on_click() callback if non is provided.

The default on_click() callback will look for these fields in the symbol instance and create a drop-down menu accordingly on click, for more information about these fields see dropbar_symbol_t.

For creating the drop-down menu:

• dropbar_symbol_t.siblings
• dropbar_symbol_t.sibling_idx
• dropbar_symbol_t.children

For jumping to the symbol or previewing it:

• dropbar_symbol_t.range
• dropbar_symbol_t.win
• dropbar_symbol_t.buf

The following example shows a source that utilizes the default on_click() callback:

local bar = require('dropbar.bar')
local custom_source = {
  get_symbols = function(buf, win, _)
    return {
      bar.dropbar_symbol_t:new({
        name = 'Section 1',
        name_hl = 'Keyword',
        siblings = {
          bar.dropbar_symbol_t:new({
            name = 'Section 2',
            name_hl = 'WarningMsg',
          }),
          bar.dropbar_symbol_t:new({
            name = 'Section 3',
            name_hl = 'Error',
          }),
          bar.dropbar_symbol_t:new({
            name = 'Section 4',
            name_hl = 'String',
            children = {
              bar.dropbar_symbol_t:new({
                buf = buf,
                win = win,
                name = 'Section 4.1',
                name_hl = 'String',
                -- Will jump to line 3, col 4 (0-indexed) when clicked in the
                -- menu
                range = {
                  start = { line = 3, character = 4 },
                  ['end'] = { line = 5, character = 6 },
                }
              }),
            },
          }),
        },
      }),
    }
  end,
}

To see this source in action add it to opts.bar.sources table:

require('dropbar').setup({
  bar = {
    sources = {
      custom_source,
    },
  },
})

Lazy-Loading Expensive Fields

If the symbol fields siblings or children are expensive to compute, you can use meta-tables to lazy-load them, so that they are only computed when a menu is opened:

local bar = require('dropbar.bar')
local custom_source = {
  get_symbols = function(_, _, _)
    return {
      bar.dropbar_symbol_t:new(setmetatable({
        name = 'Section 1',
        name_hl = 'Keyword',
      }, {
        __index = function(self, key)
          if key == 'siblings' then
            self[siblings] = -- [[ compute siblings ]]
            return self[siblings]
          end
          if key == 'children' then
            self[children] = -- [[ compute children ]]
            return self[children]
          end
          -- ...
        end,
      })),
    }
  end,
}

To see concrete examples of lazy-loading see lua/dropbar/sources.

Practical Examples

Highlight File Name Using Custom Highlight Group DropBarFileName

local dropbar = require('dropbar')
local sources = require('dropbar.source')
local utils = require('dropbar.sources')

vim.api.nvim_set_hl(0, 'DropBarFileName', { fg = '#FFFFFF', italic = true })

local custom_path = {
  get_symbols = function(buff, win, cursor)
    local symbols = sources.path.get_symbols(buff, win, cursor)
    symbols[#symbols].name_hl = 'DropBarFileName'
    if vim.bo[buff].modified then
      symbols[#symbols].name = symbols[#symbols].name .. ' [+]'
      symbols[#symbols].name_hl = 'DiffAdded'
    end
    return symbols
  end,
}

dropbar.setup({
  bar = {
    sources = function(buf, _)
      if vim.bo[buf].ft == 'markdown' then
        return {
          custom_path,
          sources.markdown,
        }
      end
      if vim.bo[buf].buftype == 'terminal' then
        return {
          sources.terminal,
        }
      end
      return {
        custom_path,
        utils.source.fallback {
          sources.lsp,
          sources.treesitter,
        },
      }
    end,
  },
})

Similar Projects

• nvim-navic