Skip to main content
The Harpoon quick menu provides a visual interface for viewing, reordering, and navigating your marked files. It’s a floating window that displays all your marks and allows you to manage them interactively.

​
Opening the quick menu

Toggle the quick menu with: 
local ui = require("harpoon.ui")

ui.toggle_quick_menu()
The menu will display all your marked files, with line numbers indicating their indices: 
╭─ Harpoon ────────────────────────────────╮
│  1  src/main.lua                         │
│  2  lib/utils.lua                        │
│  3  tests/init.lua                       │
│  4  (empty)                              │
╰──────────────────────────────────────────╯
The currently active file will be highlighted automatically when the menu opens.

​
Keyboard shortcuts

The quick menu provides several built-in keyboard shortcuts:

​
Reordering marks

You can reorder marks by editing the text in the quick menu:
  1. Open the quick menu
  2. Enter insert mode (i or a)
  3. Use Vim motions to move lines around (e.g., dd to delete, p to paste)
  4. The new order is saved automatically
-- From ui.lua:59-70
local function get_menu_items()
    local lines = vim.api.nvim_buf_get_lines(Harpoon_bufh, 0, -1, true)
    local indices = {}
    
    for _, line in pairs(lines) do
        if not utils.is_white_space(line) then
            table.insert(indices, line)
        end
    end
    
    return indices
end
Reordering marks in the UI is the easiest way to organize your workflow. Simply rearrange the lines to match your preferred navigation order.

​
Deleting marks from the UI

To remove a mark from the quick menu:
  1. Open the quick menu
  2. Navigate to the line you want to remove
  3. Delete the line (dd in normal mode)
  4. The mark is removed when the menu updates
Alternatively, you can replace a filename with (empty) to clear that slot.

​
Auto-save behavior

The quick menu respects your save_on_toggle and save_on_change configuration: 
-- From ui.lua:14-20
local function close_menu(force_save)
    local global_config = harpoon.get_global_settings()
    
    if global_config.save_on_toggle or force_save then
        require("harpoon.ui").on_menu_save()
    end
    
    vim.api.nvim_win_close(Harpoon_win_id, true)
end
When enabled, marks are saved to disk whenever you close the quick menu:
require("harpoon").setup({
    global_settings = {
        save_on_toggle = true,
    },
})
When enabled, marks are saved immediately as you edit them in the quick menu:
-- From ui.lua:141-147
if global_config.save_on_change then
    vim.cmd(
        string.format(
            "autocmd TextChanged,TextChangedI <buffer=%s> lua require('harpoon.ui').on_menu_save()",
            Harpoon_bufh
        )
    )
end

​
Customizing the menu appearance

Customize the menu size and border characters: 
require("harpoon").setup({
    menu = {
        width = 80,
        height = 15,
        borderchars = { "─", "│", "─", "│", "╭", "╮", "╯", "╰" },
    },
})
The menu is implemented as a special buffer with filetype harpoon. Make sure not to add this filetype to your mark list (it’s excluded by default).

​
Highlight groups

The quick menu uses custom highlight groups that you can configure:
  • HarpoonWindow - The main menu window
  • HarpoonBorder - The menu border
  • HarpoonCurrentFile - Highlights the currently active file
-- Example: Link to existing highlight groups
vim.cmd([[
    highlight! link HarpoonWindow Normal
    highlight! link HarpoonBorder FloatBorder
    highlight! link HarpoonCurrentFile Visual
]])

​
Direct navigation without the menu

You can navigate to marks directly without opening the menu: 
local ui = require("harpoon.ui")

-- Navigate to mark 1
ui.nav_file(1)

-- Navigate to next mark in the list
ui.nav_next()

-- Navigate to previous mark
ui.nav_prev()
These functions are particularly useful for setting up quick keybindings: 
vim.keymap.set("n", "<leader>1", function() require("harpoon.ui").nav_file(1) end)
vim.keymap.set("n", "<leader>2", function() require("harpoon.ui").nav_file(2) end)
vim.keymap.set("n", "<C-n>", function() require("harpoon.ui").nav_next() end)
vim.keymap.set("n", "<C-p>", function() require("harpoon.ui").nav_prev() end)

Build docs developers (and LLMs) love

Get started for freeTalk to us