nvim-bqf: floating preview and fzf filtering for Neovim's quickfix window

Two rendering problems in Neovim's quickfix that nvim-bqf was built to solve

Neovim's built-in quickfix window has two behaviors that become friction in a refactoring workflow. Toggling it open redistributes the vertical layout of every split on screen, which forces the eye to re-locate the code being edited. Navigating from item to item requires switching focus back and forth between the list and the edit buffer to read each context, because the stock window has no persistent preview panel.

nvim-bqf addresses both. Its magic_window feature holds the current line at a stable vertical position when the quickfix window opens in a horizontal split. A separate preview panel opens automatically beside the list and updates as you move through entries, showing each file location without any window switch. These are the two problems named in the plugin's own description, and the rest of the feature set extends from them.

Magic window: a normal Neovim split that holds its position on screen

The magic_window option defaults to true and controls what happens to the viewport when the quickfix window toggles open. A standard horizontal split redistributes vertical space across all windows and shifts the cursor line to a different position on screen. Enabling it keeps the distance between the current line and the top/bottom border of Neovim unchanged, matching the setup documentation's description of the feature.

The setup documentation also notes: "It's a bit like a floating window, but the window is indeed a normal window, without any floating attributes." That distinction matters for editor compatibility. Floating windows in Neovim carry different rules for keyboard focus, statuslines, and event handling than normal splits do; nvim-bqf achieves the stable-viewport effect without those trade-offs.

Setting this option to false reverts to standard split behavior. Anyone who has built automations or custom layouts that depend on normal split geometry should test the default before adopting the plugin.

Installing with Packer.nvim and verifying the preview with vimgrep

nvim-bqf is a Lua plugin for Neovim 0.6.1 or later. The README shows installation with Packer.nvim, deferring load to quickfix buffers with `ft = 'qf'`:

use {'kevinhwang91/nvim-bqf', ft = 'qf'}

-- optional
use {'junegunn/fzf', run = function()
    vim.fn['fzf#install']()
end
}

-- optional, highly recommended
use {'nvim-treesitter/nvim-treesitter', run = ':TSUpdate'}

After installing, open any file in Neovim and run this command to populate a quickfix list from the current buffer:

:vimgrep /\w\+/j % | copen

The quickfix window opens with the preview panel active on the side. Moving through the list updates the preview in place, which is the simplest confirmation that the plugin is working.

Without fzf installed, fzf mode is not available, but the preview panel and sign-based filtering still work. nvim-treesitter is also optional, though the setup documentation says Neovim's built-in syntax engine is "very lagging" in large files and marks treesitter as highly recommended.

Sign-based filtering: marking items and building a focused quickfix list

Signs in nvim-bqf are markers placed on individual items in the quickfix window. Toggle the sign of an item with `<Tab>` or `<S-Tab>`. After signing a set, create a new quickfix list with `zn` or `zN`; the README describes this as filtering the items of the quickfix window using signs.

Neither command modifies the original list: a new entry appears on the history stack, leaving the full search result reachable. For a batch rename where some match locations should be skipped, toggling signs on those entries first and then creating a filtered list separates the candidates without discarding the original result. That non-destructive behavior is what makes iterative narrowing practical.

In fzf mode, input `^^` in fzf prompt to find all signed items. Using this brings fzf's narrowing interface to bear on the signed subset before a new list is built.

Fzf mode: split opens, sign toggling, and injecting preview bindings

fzf mode is opened by pressing `zf`. fzf in nvim-bqf supports `ctrl-t`/`ctrl-x`/`ctrl-v` key bindings that allow you to open up an item in a new tab, a new horizontal split, or in a new vertical split.

Use `ctrl-q` in fzf mode to toggle items' sign. Those signs carry back to the quickfix window when fzf closes.

For the fzf preview scroll, two methods appear in the documentation. Setting `$FZF_DEFAULT_OPTS` to contain `--bind=ctrl-f:preview-half-page-down,ctrl-b:preview-half-page-up` applies those bindings to all fzf invocations. Alternatively, scope the bindings to nvim-bqf alone through the `extra_opts` key in the setup call:

extra_opts = {'--bind', 'ctrl-f:preview-half-page-down,ctrl-b:preview-half-page-up'}

fzf 0.42.0 or later is required for this integration. Older versions are not supported.

auto_resize_height defaults to false and is absent from the minimal configuration

The preview window draws from actual Neovim buffers, which is why treesitter syntax applies to it. When a treesitter parser is installed for the filetype being previewed, the preview panel uses the same parser that highlights the edit buffer. Without treesitter, Neovim falls back to its regex-based syntax engine, which the setup documentation says causes problems severe enough to hurt the user experience in large files.

One option the minimal configuration omits is auto_resize_height, which defaults to false. When enabled, it shrinks the quickfix window's height to fit the actual number of items, or extends it to a default height of 10 when the list is short. With the default of false, the window opens at whatever height Neovim assigns regardless of list length.

Any user who resizes the quickfix window manually after it opens should enable this option in their plugin setup. Nothing in the minimal configuration or the usage examples points to it, so the option requires deliberate discovery.

Three open TODO items and a context feature that is documented but incomplete

Three items appear on nvim-bqf's own TODO list in the README. History navigation is one of them: the listed goal is to "Find a better way to list history and switch to one." A second item reads "Use context field to override the existed configuration," and this stands out because a dedicated section in the README documents the quickfix context feature with coverage of why it was introduced, which keys it supports, and sample Lua tests. Context is implemented; applying context values to override per-buffer plugin configuration is what the TODO marks as unfinished.

"Add tests" is the third open item. Running a plugin with no automated test suite means no check against regressions when future changes land.

BSD-3-Clause governs the project, and v1.1.1 is the most recent tagged release, published on 2024-02-20. The last push was on 2026-04-02, and the repository is not archived.

Editorial conclusion

nvim-bqf is for Neovim users who rely on quickfix for refactoring, LSP diagnostics, or any workflow that generates quickfix lists regularly. The preview panel and sign-based filter address the two main friction points without replacing the native quickfix buffer, so existing keymaps carry over. fzf mode requires fzf 0.42.0 or later; the treesitter-optimized preview requires nvim-treesitter. Before adopting it, confirm your Neovim version meets the 0.6.1 requirement, check whether the incomplete history-navigation feature in the TODO list matters to your workflow, and note that the project has no automated test suite.

Frequently asked questions

Official sources

1. Issues
2. kevinhwang91/nvim-bqf on GitHub
3. License: BSD-3-Clause
4. README
5. Releases