fff.nvim Keybinds: Complete Guide to Default Mappings and Customization

fff.nvim ships with intuitive default key mappings for navigation, selection, and preview control defined in lua/fff/conf.lua, all of which can be customized via the setup configuration.

The dmtrKovalenko/fff.nvim plugin provides a blazing-fast fuzzy file finder for Neovim. Understanding the default fff.nvim keybinds is essential for efficient workflow, as these mappings control everything from closing the picker to managing multi-select and preview scrolling.

Default fff.nvim Keybinds

The plugin defines sensible defaults in lua/fff/conf.lua (lines 31‑53) that cover navigation, selection, and window management. These are wired into the UI via M.setup_keymaps() in lua/fff/picker_ui.lua (lines 804‑842).

Navigation and Selection

• Close picker: <Esc> (works in input, list, and preview buffers)
• Select entry: <CR> (confirm selection)
• Select in split: <C-s> (horizontal split)
• Select in vertical split: <C-v> (vertical split)
• Select in new tab: <C-t> (open in new tab)
• Move cursor up: <Up>, <C-p>
• Move cursor down: <Down>, <C-n>

Window Management and Preview

• Scroll preview up: <C-u> (preview buffer with fallback to input/list)
• Scroll preview down: <C-d> (preview buffer with fallback to input/list)
• Focus list window: <leader>l (normal mode in list buffer)
• Focus preview window: <leader>p (normal mode in list buffer)
• List-buffer navigation: j / k (move down/up in normal mode)
• List-buffer quit: q (close picker)
• List-buffer jump to input: i (focus the input prompt)

Advanced Actions

• Toggle multi-select: <Tab> (enable selecting multiple items)
• Send to quick-fix: <C-q> (send selected items to quickfix list)
• Cycle grep modes: <S-Tab> (switch between grep modes)
• Toggle debug scores: <F2> (show/hide debug information)
• Recall previous query: <C-Up> (input buffer only)

Source Code Architecture for Keybinds

According to the dmtrKovalenko/fff.nvim source code, the keymap system relies on two core files. The default configuration lives in lua/fff/conf.lua, specifically within the keymaps table spanning lines 31‑53. This table defines every available action and its default key sequence.

The wiring implementation occurs in lua/fff/picker_ui.lua through the M.setup_keymaps() function (lines 804‑842). This function binds the configured keys across three buffer contexts: the input buffer, the list buffer, and the preview buffer. Some bindings apply globally across all picker buffers, while others are context-specific—for example, <C-u> and <C-d> primarily control preview scrolling but fall back to working in input and list buffers when the preview window is active.

Customizing fff.nvim Keybinds

Users can override any default mapping by passing a keymaps table to the setup function. The plugin merges user-defined keys with defaults using the configuration system in conf.lua, which reads from vim.g.fff and applies the merged result via picker_ui.lua.

require('fff').setup({
  keymaps = {
    close = 'q',                          -- Press q to close instead of Esc
    move_up = { '<Up>', '<C-p>', 'k' },   -- Add 'k' as alternative
    select_vsplit = '<C-\\>',              -- Change vertical split binding
  },
})

For Vimscript users, you can launch the picker with custom command mappings while keeping the internal keybind configuration in Lua:

" Map <leader>f to open the picker
nnoremap <leader>f :FFF<CR>

Summary

• Default fff.nvim keybinds are defined in lua/fff/conf.lua (lines 31‑53) and implemented in lua/fff/picker_ui.lua (lines 804‑842).
• Navigation uses standard arrows and Ctrl combinations, while <CR> selects and <Esc> closes the picker.
• Preview scrolling uses <C-u>/<C-d>, and multi-select toggles with <Tab>.
• All mappings are customizable via the keymaps table in the setup configuration.

Frequently Asked Questions

How do I change the default close key in fff.nvim?

Pass a custom keymaps table to the setup function with the close key set to your preferred mapping. For example, set close = 'q' to use the q key instead of Escape.

Can I add additional keys for the same action in fff.nvim?

Yes, the configuration accepts arrays for any action. Specify multiple keys like move_up = { '<Up>', '<C-p>', 'k' } to enable all three methods for moving up the list, as implemented in the configuration merging logic.

Where are the fff.nvim keymaps actually bound in the source code?

The default definitions reside in lua/fff/conf.lua, while the actual binding logic executes in lua/fff/picker_ui.lua within the M.setup_keymaps() function, which applies the mappings to input, list, and preview buffers during UI initialization.

Do fff.nvim keybinds work differently in grep mode?

The <S-Tab> binding specifically cycles through grep modes when the picker is in grep mode, while most other navigation and selection bindings remain consistent across all picker modes according to the source implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}