# fff.nvim Default Settings: Complete Configuration Reference

> Explore the fff.nvim default settings. Discover the built-in configuration for window dimensions, result limits, worker threads, and keymaps. Get started with fff.nvim effortlessly.

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

---

**fff.nvim ships with a comprehensive default configuration defined in [`lua/fff/conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua) that requires no user setup, including 80% window dimensions, 100-result limits, 4 worker threads, and built-in keymaps for file navigation.**

The dmtrKovalenko/fff.nvim plugin is designed to be fully functional immediately after installation thanks to sensible factory settings. All fff.nvim default settings are centralized in the `init()` function within [`lua/fff/conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua), specifically within the `default_config` table spanning lines 89-339, which defines every UI parameter, performance limit, and keybinding. Users can selectively override any value while retaining the remaining factory settings through the `setup()` API.

## Complete Default Settings Reference

All fff.nvim default settings are organized by functional area within the `default_config` table in [`lua/fff/conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua). These values are loaded automatically when the plugin initializes.

### General Options

The core behavior defaults define how the picker operates:
- `base_path = cwd` – Uses the current working directory as the search root
- `prompt = "🪿 "` – The default picker prompt character
- `title = "FFFiles"` – Window title text
- `max_results = 100` – Maximum files displayed in results
- `max_threads = 4` – Number of concurrent worker threads
- `lazy_sync = true` – Enables asynchronous result streaming

### Window Layout

Window positioning and sizing defaults control the UI geometry:
- `height = 0.8` and `width = 0.8` – Occupies 80% of the editor screen
- `prompt_position = "bottom"` – Input field appears at the bottom
- `preview_position = "right"` – File preview panel appears on the right
- `preview_size = 0.5` – Preview occupies 50% of the picker width
- `flex = { size = 130, wrap = "top" }` – Responsive layout breakpoints
- `show_scrollbar = true` – Displays scroll indicators
- `path_shorten_strategy = "middle_number"` – Shortens long paths in the middle

### File Preview

Preview rendering defaults determine how file contents are displayed:
- `enabled = true` – Preview pane is active by default
- `max_size = 10485760` (10 MiB) – Files larger than this are not previewed
- `chunk_size = 8192` – Read buffer size for file operations
- `binary_file_threshold = 1024` – Byte check threshold for binary detection
- `imagemagick_info_format_str = "%m: %wx%h, %[colorspace], %q-bit"` – Format string for image metadata
- `line_numbers = false` – Line numbers hidden in preview
- `cursorlineopt = "both"` – Cursor line highlighting mode
- `wrap_lines = false` – Text wrapping disabled by default (except for SVG, Markdown, and text files)

### Keymaps

Default keyboard shortcuts use standard Vim conventions:
- `close = "<Esc>"` – Exit the picker
- `select = "<CR>"` – Open file in current window
- `select_split = "<C-s>"` – Open in horizontal split
- `select_vsplit = "<C-v>"` – Open in vertical split
- `select_tab = "<C-t>"` – Open in new tab
- `move_up = {"<Up>", "<C-p>"}` and `move_down = {"<Down>", "<C-n>"}` – Navigation alternatives
- `preview_scroll_up = "<C-u>"` and `preview_scroll_down = "<C-d>"` – Preview scrolling
- `toggle_select = "<Tab>"` – Multi-select files
- `send_to_quickfix = "<C-q>"` – Send results to quickfix list
- `cycle_grep_modes = "<S-Tab>"` – Switch between plain/regex/fuzzy search
- `toggle_debug = "<F2>"` – Debug panel toggle
- `focus_list = "<leader>l"` and `focus_preview = "<leader>p"` – Window focus commands

### Frecency and History

Ranking and persistence defaults improve result relevance:
- **Frecency**: `enabled = true` with `db_path` set to `stdpath('cache')..'/fff_nvim'` tracks file open frequency
- **History**: `enabled = true` with `db_path` at `stdpath('data')..'/fff_queries'` stores successful queries, requiring `min_combo_count = 3` for persistence and applying a `combo_boost_score_multiplier = 100` for repeated selections

### Highlight Groups

Default highlight group mappings link to standard Vim colors:
- `border = "FloatBorder"`
- `normal = "Normal"`
- `matched = "IncSearch"`
- `title = "Title"`
- `prompt = "Question"`
- `cursor` falls back to `"CursorLine"` or `"Visual"`

### Grep Engine and Git Integration

Built-in search and version control defaults limit resource usage:
- `max_file_size = 10485760` (10 MiB)
- `max_matches_per_file = 100`
- `smart_case = true`
- `time_budget_ms = 150`
- `modes = { "plain", "regex", "fuzzy" }`
- Git `status_text_color = false` – Only the sign column is colored by default

### Debug and Logging

Diagnostic defaults remain off unless explicitly enabled:
- **Debug**: `enabled = false` and `show_scores = false`
- **Logging**: `enabled = true` with `log_file = stdpath('log')..'/fff.log'` and `log_level = "info"`
- **File Picker**: `current_file_label = "(current)"` marks the active buffer

## How Default Settings Are Loaded

The configuration system in [`lua/fff/conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua) follows a strict initialization pipeline. The `init()` function first retrieves any existing user configuration from `vim.g.fff`, then processes deprecated options through `handle_deprecated_config`.

The final configuration is built using `vim.tbl_deep_extend('force', default_config, migrated_user_config)`, which recursively merges user values over the factory defaults. This merged table is cached in the module's `state.config` and accessible via `M.get()` for consumption by picker components.

## Customizing the Defaults

While fff.nvim works without configuration, you can selectively override any setting while preserving others.

### Use All Defaults

To run the plugin with factory settings only:

```lua
require('fff').setup() -- No arguments required
vim.keymap.set('n', '<leader>f', function()
  require('fff').open()
end)

```

### Override Specific Options

Pass a partial configuration table to modify individual values:

```lua
require('fff').setup {
  prompt = '🔍 ',
  layout = {
    preview_position = 'left'
  },
  keymaps = {
    close = 'q',
  },
}

```

### Replace Highlight Groups

To completely replace the highlight configuration sub-table:

```lua
require('fff').setup {
  hl = {
    border = 'FloatBorder',
    matched = 'Search',
    title = 'Title',
    git_modified = 'DiffChange',
  },
}

```

### Disable Features

Turn off specific components like the preview pane:

```lua
require('fff').setup {
  preview = { enabled = false },
}

```

## Source Files in the Configuration Pipeline

Several core files consume the default settings during initialization:

| File | Role |
|------|------|
| [`lua/fff/conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua) | Defines `default_config`, handles migration via `handle_deprecated_config`, and exports the merged configuration via `M.get()` |
| [`lua/fff/core.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/core.lua) | Core picker logic that reads configuration for layout decisions and keymap registration |
| [`lua/fff/file_picker/init.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/file_picker/init.lua) | Implements file-listing UI using `config.layout` and `config.preview` |
| [`lua/fff/grep/init.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/grep/init.lua) | Implements grep functionality consuming `config.grep` limits |
| [`lua/fff/picker_ui.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/picker_ui.lua) | Renders borders, titles, and prompts based on `config.hl` |

## Summary

- **fff.nvim default settings** are defined in [`lua/fff/conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua) (lines 89-339) within the `default_config` table
- The plugin requires no configuration and uses sensible defaults including 80% window size, 100-result limits, and 4 worker threads
- Settings are loaded via `init()` which deep-merges user options from `vim.g.fff` over the factory defaults
- All parameters can be overridden selectively while retaining remaining defaults through `require('fff').setup()`
- Key components including the preview pane, frecency tracking, and grep engine can be individually configured or disabled

## Frequently Asked Questions

### Where are fff.nvim default settings stored?

The default settings are stored in [`lua/fff/conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua) inside the `default_config` table, specifically between lines 89 and 339. This file contains the `init()` function that processes user overrides and returns the final configuration to the rest of the plugin.

### Do I need to configure fff.nvim for it to work?

No. fff.nvim is fully functional without any user configuration. Calling `require('fff').setup()` with no arguments will load all factory defaults, including window dimensions, keymaps, and preview behavior, making the picker ready for immediate use.

### How do I override a default setting without losing the rest?

Pass a partial configuration table to `setup()`. The plugin uses `vim.tbl_deep_extend('force', default_config, user_config)` to merge your changes, so only specified fields are replaced. For example, setting `{ prompt = '> ' }` changes only the prompt while keeping all other defaults intact.

### Can I disable the preview window by default?

Yes. Set `preview = { enabled = false }` in your setup configuration. This completely disables the file preview pane while preserving all other default behaviors like keymaps, result limits, and window sizing.