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

> Master fff.nvim configuration options to customize your Neovim file picker. Learn about layout, keymaps, preview, and search settings for a personalized workflow.

- Repository: [Dmitriy Kovalenko/fff.nvim](https://github.com/dmtrKovalenko/fff.nvim)
- Tags: how-to-guide
- Published: 2026-04-04

---

**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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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.

```lua
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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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}}`.

```lua
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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`

```lua
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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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.

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

```

## Grep Configuration

Configure live search behavior with options from lines 292‑298 of **[`lua/fff/conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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.

```lua
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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua)**). Override these to match your colorscheme.

```lua
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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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:

```lua
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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua)**).

```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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua)**.