fff.nvim Default Settings: Complete Configuration Reference

fff.nvim ships with a comprehensive default configuration defined in 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, 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. 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 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:

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:

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

Replace Highlight Groups

To completely replace the highlight configuration sub-table:

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

Disable Features

Turn off specific components like the preview pane:

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	Defines default_config, handles migration via handle_deprecated_config, and exports the merged configuration via M.get()
lua/fff/core.lua	Core picker logic that reads configuration for layout decisions and keymap registration
lua/fff/file_picker/init.lua	Implements file-listing UI using config.layout and config.preview
lua/fff/grep/init.lua	Implements grep functionality consuming config.grep limits
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 (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 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.

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