fff.nvim Configuration Options: A Complete Guide to Customizing Your File Picker

Configure fff.nvim by setting a Lua table in vim.g.fff or calling require('fff.conf').setup(), which merges your settings with sensible defaults defined in lua/fff/conf.lua to control layout, keymaps, preview behavior, and search functionality.

fff.nvim is a fast, feature-rich file picker for Neovim built with a Rust core and Lua interface. Understanding the available fff.nvim configuration options allows you to customize everything from window dimensions to grep modes and git highlighting. All settings are managed through a central configuration table that the plugin reads from vim.g.fff or via the explicit setup function.

Layout Configuration

The layout section controls the dimensions and positioning of the picker window and preview pane. These options are defined in lines 99‑115 of lua/fff/conf.lua.

• layout.height (number, default: 0.8): Fraction of screen height used by the picker.
• layout.width (number, default: 0.8): Fraction of screen width.
• layout.prompt_position ("top" or "bottom", default: "bottom"): Where the prompt line appears.
• layout.preview_position ("right", "left", "top", or "bottom", default: "right"): Side for the file preview.
• layout.preview_size (number, default: 0.5): Relative size of the preview pane.
• layout.flex (table, default: {size = 130, wrap = 'top'}): Responsive layout rules; if terminal width ≥ size, preview uses preview_position, otherwise it wraps according to wrap.
• layout.show_scrollbar (boolean, default: true): Display scrollbar for pagination.
• layout.path_shorten_strategy ("middle_number", "middle", or "end", default: "middle_number"): Truncation method for long directory names.

vim.g.fff = {
  layout = {
    height = 0.9,
    width  = 0.9,
    preview_position = 'left',
    preview_size = 0.4,
    flex = nil,               -- disable responsive flex layout
    path_shorten_strategy = 'end',
  },
}

Preview Configuration

Fine-tune the in-picker preview buffer using options found in lines 116‑131 of lua/fff/conf.lua.

• preview.enabled (boolean, default: true): Toggle the preview pane.
• preview.max_size (number, default: 10485760 bytes): Maximum file size to preview (default 10 MiB).
• preview.chunk_size (number, default: 8192): Bytes read per lazy-load step.
• preview.binary_file_threshold (number, default: 1024): Bytes examined to detect binary files; set to 0 to disable detection.
• preview.imagemagick_info_format_str (string): Format string for ImageMagick image previews.
• preview.line_numbers (boolean, default: false): Show line numbers in preview.
• preview.cursorlineopt (string, default: 'both'): Cursor-line highlight option.
• preview.wrap_lines (boolean, default: false): Enable line wrapping.
• preview.filetypes (table): Per-filetype overrides, e.g., {svg = {wrap_lines = true}}.

vim.g.fff = {
  preview = {
    line_numbers = true,
    wrap_lines = false,
    filetypes = {
      txt = { wrap_lines = true },
      md  = { wrap_lines = true },
    },
  },
}

Keymaps Configuration

All interactive commands are configurable through the keymaps table, accepting either a single string or a list of alternatives (lines 132‑152 of lua/fff/conf.lua).

• close: <Esc>
• select: <CR>
• select_split: <C-s>
• select_vsplit: <C-v>
• select_tab: <C-t>
• move_up: { '<Up>', '<C-p>' }
• move_down: { '<Down>', '<C-n>' }
• preview_scroll_up: <C-u>
• preview_scroll_down: <C-d>
• toggle_debug: <F2>
• cycle_grep_modes: <S-Tab>
• cycle_previous_query: <C-Up>
• toggle_select: <Tab>
• send_to_quickfix: <C-q>
• focus_list: <leader>l
• focus_preview: <leader>p

vim.g.fff = {
  keymaps = {
    close = 'jj',
    move_up   = { '<C-k>' },
    move_down = { '<C-j>' },
  },
}

Frecency and History Settings

Control smart ranking and query history persistence (lines 159‑171 of lua/fff/conf.lua).

• frecency.enabled (boolean, default: true): Track file-open frequencies for ranking.
• frecency.db_path (string): SQLite database location (defaults to stdpath('cache')..'/fff_nvim').
• history.enabled (boolean, default: true): Store past queries and results.
• history.db_path (string): History database file (defaults to stdpath('data')..'/fff_queries').
• history.min_combo_count (number, default: 3): Minimum consecutive selections before combo boost.
• history.combo_boost_score_multiplier (number, default: 100): Score multiplier for combo boosts.

vim.g.fff = {
  frecency = { enabled = false },
}

Grep Configuration

Configure live search behavior with options from lines 292‑298 of lua/fff/conf.lua.

• grep.max_file_size (number, default: 10485760 bytes): Skip files larger than this (10 MiB).
• grep.max_matches_per_file (number, default: 100): Match limit per file (0 for unlimited).
• grep.smart_case (boolean, default: true): Case-insensitive unless pattern contains uppercase.
• grep.time_budget_ms (number, default: 150): Maximum time per grep call (0 for unlimited).
• grep.modes (list, default: { 'plain', 'regex', 'fuzzy' }): Available grep modes and cycling order.

vim.g.fff = {
  grep = {
    modes = { 'regex', 'plain', 'fuzzy' },
    time_budget_ms = 0,
  },
}

Git Integration and Highlight Groups

Git status displays as signs or colored filenames based on highlight groups defined under the hl key (lines 155‑190 of lua/fff/conf.lua). Override these to match your colorscheme.

vim.g.fff = {
  hl = {
    git_sign_staged = 'MyGitStagedHl',
  },
}

Debugging and Logging

Control runtime diagnostics and log output (lines 190‑205 of lua/fff/conf.lua).

• debug.enabled (boolean, default: false)
• debug.show_scores (boolean, default: false): Display match scores in UI.
• logging.enabled (boolean, default: true)
• logging.log_file (string): Log file path (defaults to stdpath('log')..'/fff.log').
• logging.log_level (string, default: 'info')

Toggle debugging at runtime without restarting:

require('fff.conf').toggle_debug()   -- toggles debug.show_scores and debug.enabled

How to Apply Your Configuration

You can configure fff.nvim in two ways. Set vim.g.fff before the plugin loads, or call require('fff.conf').setup(your_table) at any time. The plugin merges your values with defaults via the init() function (lines 89‑103 of lua/fff/conf.lua).

-- init.lua
vim.g.fff = {
  layout = { width = 0.7, height = 0.85 },
  preview = { line_numbers = true },
  keymaps = { close = '<C-c>' },
}
require('fff').setup()   -- optional early initialization

Summary

• fff.nvim configuration options are defined in a single table assigned to vim.g.fff or passed to require('fff.conf').setup().
• lua/fff/conf.lua contains all default values and the merging logic for user overrides.
• Key sections include layout (dimensions and flex), preview (file viewing settings), keymaps (input bindings), frecency/history (ranking and persistence), and grep (live search parameters).
• Debugging can be toggled dynamically using require('fff.conf').toggle_debug().

Frequently Asked Questions

How do I change the default keybindings in fff.nvim?

Assign values to the keymaps table in your configuration. Keys can be single strings or lists of alternative keys. For example, set vim.g.fff.keymaps.close = 'jj' to use jj for closing the picker, as implemented in lines 132‑152 of lua/fff/conf.lua.

Can I disable the file preview window entirely?

Yes, set preview.enabled = false in your configuration table. This completely disables the preview pane regardless of layout settings, according to the preview options in lines 116‑131 of lua/fff/conf.lua.

Where does fff.nvim store its database files?

By default, frecency data stores in stdpath('cache')..'/fff_nvim' and history stores in stdpath('data')..'/fff_queries'. You can override these paths using frecency.db_path and history.db_path respectively, as specified in lines 159‑171 of lua/fff/conf.lua.

How do I enable debugging to see match scores?

Set debug.enabled = true and debug.show_scores = true in your configuration, or call require('fff.conf').toggle_debug() at runtime to toggle the debug UI. Debug settings are defined in lines 190‑205 of lua/fff/conf.lua.

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