fzf-tab: the zsh completion menu, fed through fzf

It shows completions, it does not make them

The README's difference section is the whole philosophy in two sentences, fzf-tab doesn't do complete, it just shows you the results of the default completion system. Everything else follows, it works everywhere the native system works, variables, function names, the directory stack, in-word completion, and most configuration for the default completion system remains valid, the zstyle tuning a user accumulated over years keeps acting underneath the new menu. This is the architectural decision that separates it from the fzf completion scripts that bring their own matching logic and only handle certain contexts. The plugin is shell, MIT-licensed, a single plugin file plus a library directory, and the current line is v1.3.0 from 2026-03-16, with the repository last pushed on 2026-06-04. The tagline is replace zsh's default completion selection menu with fzf, and the asciinema recording linked at the top shows the before and after in a few seconds, still the fastest way to understand what the plugin changes. The plugin's honesty about its own scope is what makes the coverage claim credible, it never promises matching quality, only faithful presentation of what compinit already produced.

The load-order rule that decides whether it works

Installation is offered through five managers, but the important part is the warning block above all of them, three requirements that decide success or silent failure. First, fzf itself must be installed, the plugin being a consumer rather than a replacement. Second, fzf-tab needs to load after compinit but before plugins that wrap widgets, zsh-autosuggestions and fast-syntax-highlighting named explicitly. Third, completions should be configured before compinit, as the zsh-completions manual states, an upstream rule the README passes along rather than restates. The manual install makes the ordering visible:

autoload -U compinit; compinit
source ~/somewhere/fzf-tab.plugin.zsh

The manager variants are one line each, antigen bundle Aloxaf/fzf-tab, zinit light Aloxaf/fzf-tab, an Oh-My-Zsh clone into the custom plugins directory, or a Prezto clone into contrib, and the compatibility section adds the sharper form of the rule, make fzf-tab the last plugin to bind Tab, put it at the end of the plugin list, because anything binding afterwards without handling the previous widget breaks the chain fzf-tab relies on. Most breakage reports trace to this one ordering mistake.

Press Tab, then Ctrl-Space, F1 and slash

Usage begins with nothing to learn, press Tab as usual, and the completion list appears in an fzf finder instead of a menu. Three bindings extend it. Ctrl+Space selects multiple results at once, configured through the fzf-bindings tag, the multi-select that native zsh menus handle awkwardly. F1 and F2 switch between completion groups, configured through switch-group, jumping between the groups a descriptions zstyle already defines. The slash key triggers continuous completion, configured through continuous-trigger, aimed at deep paths, the mode where completing one directory level immediately offers the next instead of requiring repeated Tab presses, the feature that most changes day-to-day feel on deep trees. Three commands manage the plugin at runtime, disable-fzf-tab to fall back to compsys, enable-fzf-tab to restore it, and toggle-fzf-tab flipping the state, the last also being a zle widget that can be bound directly.

Configuration is still just zstyle

Because the native completion system remains the engine, configuration remains the zstyle vocabulary, and the README's common-configuration block is a working example of the interplay. Disabling sort for git checkout, zstyle ':completion:*:git-checkout:*' sort false, keeps branch order stable in the finder. Setting the descriptions format to '[%d]' enables group support, with a documented caveat, escape sequences like '%F{red}%d%f' are ignored by fzf-tab, so colors belong elsewhere. Setting list-colors from LS_COLORS enables filename colorizing, and setting menu no forces zsh not to show its own completion menu, which allows fzf-tab to capture the unambiguous prefix, the setting most users miss. A preview example colors directory contents with eza when completing cd, the fzf preview pane serving as the file listing. The wiki's Configuration page extends all of this, and the through-line is that nothing is a new language, it is zsh completion configuration with an fzf presentation layer. Teams sharing dotfiles benefit most, the completion config they already version continues to work, and the fzf layer arrives as one plugin line rather than a rewrite.

ftb-tmux-popup and the tmux 3.2 payoff

For tmux users at 3.2 or newer, the plugin ships ftb-tmux-popup, a script making full use of tmux's popup feature, wired in with a single line:

zstyle ':fzf-tab:*' fzf-command ftb-tmux-popup

The popup replaces the inline finder with a floating window, the presentation fzf uses in modern terminal emulators, delivered through tmux itself so it works everywhere tmux does. The script is deliberately usable outside the plugin too, the README demonstrating ls piped into ftb-tmux-popup, a generic popup wrapper that happens to ship with fzf-tab, a small bonus that makes the script worth knowing even for users of other completion setups. The asciinema recording linked beside it shows the popup in motion, and the wiki carries the deeper configuration. For users on older tmux the default command path applies, and the zstyle's fzf-command slot itself is the general extension point for any wrapper.

A binary module for coloring many files

One performance corner is documented with its remedy. By default the plugin uses zsh-ls-colors to parse and apply ZLS_COLORS when the list-colors tag is set, but that implementation is pure zsh script and slow when too many files need colorizing, the exact case a completion listing of a large directory produces. fzf-tab ships an optional binary module to speed the process, built with the build-fzf-tab-module command, and once built it is enabled automatically, no configuration toggle to find. The modules directory in the repository holds the source, and the split is the honest kind, a fast pure-shell default with an opt-in native accelerator for the workload that needs it. For most setups the pure version is fine, and the module exists for the users whose ls-colors parsing became the visible pause in every completion.

The neighbors, and which one you want

The ecosystem question is which fzf-flavored completion to run, and the README answers it twice, in the difference section and the related list. fzf's own shell/completion.zsh binds Tab with custom widgets and its own matching, covering file paths well but not everywhere native completion reaches, while fzf-tab keeps compinit as the engine and gains its coverage of variables, functions and the directory stack. lincheney's fzf-tab-completion extends the idea to zsh, bash and GNU readline applications, the choice when the same interaction must follow you into other shells and readline-based tools. Oh-My-Zsh's completion library also binds Tab, which is why the load-order rule exists, fzf-tab calling the previously bound widget to gather its list. For the zsh user with an established completion configuration, the wrapping approach is the least disruptive path to an fzf presentation, and the version history, v1.1.2 in 2024, v1.2.0 in 2025 and v1.3.0 in 2026, shows a plugin that changes slowly because its job is narrow and its foundation is stable.

Editorial conclusion

Use fzf-tab when zsh's native completion is already configured well and only the selection menu is the pain, since it wraps rather than replaces compinit and inherits every zstyle already tuned. Prefer fzf's own completion.zsh when a standalone fzf-driven file finder suffices, or lincheney's fzf-tab-completion when bash and GNU readline applications must gain the same behavior. Verify first the load-order rule, after compinit, after completions are configured, and last among plugins binding Tab, keep the tmux popup variant in mind if you run 3.2 or newer, and build the binary module when coloring large file lists.

Frequently asked questions

Official sources

1. Aloxaf/fzf-tab on GitHub
2. Issues
3. License: MIT
4. README
5. Releases