Configuration - Aloxaf/fzf-tab GitHub Wiki



fzf-tab uses zstyle for configuration. It can give you more control over fzf-tab's behavior, eg:

# disable sort when completing options of any command
zstyle ':completion:complete:*:options' sort false

# use input as query string when completing zlua
zstyle ':fzf-tab:complete:_zlua:*' query-string input

fzf-tab is configured via command like this: zstyle ':fzf-tab:{context}' tag value. fzf-tab is the top context. My English is not good. You can see zsh's doc for more information about zstyle.

You can use C-x h to get possible context for a command:


  • You need to use enable-fzf-tab to active fzf-tab again after this command.
  • Add bindkey '^Xh' _complete_help to your zshrc if C-x h is not bound.
❯ rg -- # Press `C-x h` here
tags in context :completion::complete:rg::
    operand-argument-1 options  (_arguments _rg _ripgrep)
tags in context :completion::complete:rg:options:
    options  (_arguments _rg _ripgrep)
tags in context :completion::files-enhance:::
    globbed-files  (_files _files_enhance)

Here are available tags in fzf-tab context:


Specify the fuzzy search program.

By default, fzf-tab use orignal fzf as the fuzzy searcher. But it also provides a wrapper named ftb-tmux-popup, which can use tmux popup (require tmux 3.2) to show results.


You can enable it with zstyle ':fzf-tab:*' fzf-command ftb-tmux-popup

Default value:

zstyle ':fzf-tab:*' fzf-command fzf


It can be used to add custom keybindings to fzf, like zstyle ':fzf-tab:*' fzf-bindings 'ctrl-j:accept' 'ctrl-a:toggle-all'

These bindings are simply passed through to fzf. See the fzf manual for more details.

You can use {_FTB_INIT_} to initialize some special variables for further usage.


zstyle ':fzf-tab:complete:*' fzf-bindings \
	'ctrl-v:execute-silent({_FTB_INIT_}code "$realpath")' \
    'ctrl-e:execute-silent({_FTB_INIT_}kwrite "$realpath")'

Default value: None


The code for previewing.

For more information about previewing, please see Preview


Any extra flags for fzf-command.

Default value: None


How many lines does fzf's prompt occupied. You may need to set this to 4 if you have set --border for fzf.

Default value: 2


Minimal height of fzf's prompt. You may want to increase it if you use fzf-preview.

Default value: 0


It specifies the key to accept and run a suggestion in one keystroke.


zstyle ':fzf-tab:*' fzf-bindings 'space:accept'
zstyle ':fzf-tab:*' accept-line enter

Default value: None


It specifies the key to trigger a continuous completion (accept the result and start another completion immediately). It's useful when completing a long path.

Default value: zstyle ':fzf-tab:*' continuous-trigger '/'

To disable continuous-trigger for a specific command, use: zstyle ':fzf-tab:*<CMD>*' continuous-trigger ''

Where <CMD> is the command, with aliases expanded.


Pressing this key will use the currently entered user input as the final completion output (#148).

Default value: zstyle ':fzf-tab:*' print-query alt-enter


Switch over different groups (#183).

Default value: zstyle ':fzf-tab:*' switch-group F1 F2


The strategy for generating query string.

Possible values:

  • input: use user's input as query string, just like zsh's default behavior
  • prefix: use the longest common prefix for all candidates as the query string
  • first: just a flag. If set, the first valid query string will be used
  • longest: another flag. If set, the longest valid query string will be used

Default value: zstyle ':fzf-tab:*' query-string prefix input first


A prefix to indicate the color.

Default value: zstyle ':fzf-tab:*' prefix '·'

NOTE: If not set zstyle ':completion:*:descriptions' format, it will be set to empty.


Color when there is no group.

Default value: zstyle ':fzf-tab:*' default-color $'\033[37m' (white)


What to show when there is only one group.

Possible values:

  • prefix: show color prefix
  • color: show group color
  • header: show group header

Default value: zstyle ':fzf-tab:*' single-group color header


Color for different groups and their descriptions.

Default value:

    $'\033[94m' $'\033[32m' $'\033[33m' $'\033[35m' $'\033[31m' $'\033[38;5;27m' $'\033[36m' \
    $'\033[38;5;100m' $'\033[38;5;98m' $'\033[91m' $'\033[38;5;80m' $'\033[92m' \
    $'\033[38;5;214m' $'\033[38;5;165m' $'\033[38;5;124m' $'\033[38;5;120m'
zstyle ':fzf-tab:*' group-colors $FZF_TAB_GROUP_COLORS

To choose the color you want, you can first use this function to print the palette:

# Usage: palette
palette() {
    local -a colors
    for i in {000..255}; do
    print -cP $colors

And then use this helper function to get escape sequence for the color code:

# Usage: printc COLOR_CODE
printc() {
    local color="%F{$1}"
    echo -E ${(qqqq)${(%)color}}


When zstyle ':completion:*:descriptions' format is set, fzf-tab will display these group descriptions as headers.

Set to full to show all descriptions, set to brief to only show descriptions for groups with duplicate members, and set to none to hide all.

Default value: zstyle ':fzf-tab:*' show-group full


It is possible to use fzf-tab with an allowlist/denylist of commands.

Set to any to disable fzf-tab everywhere, set to files to disable fzf-tab on files completion, and set to none to enable fzf-tab everywhere.


zstyle ':fzf-tab:*' disabled-on any
zstyle ':fzf-tab:complete:<command in allowlist>:*' disabled-on none


zstyle ':fzf-tab:complete:<command in denylist>:*' disabled-on any

Default value: zstyle ':fzf-tab:*' disabled-on none



The right and bottom padding of the popup window. It is exclusively useful for modifying the tmux popup window's padding.

zstyle ':fzf-tab:complete:cd:*' fzf-preview 'exa -1 --color=always $realpath'
zstyle ':fzf-tab:complete:cd:*' popup-pad 30 0

Default value: None


Minimal size of the popup window. You may want to increase it if you use fzf-preview.


# apply to all command
zstyle ':fzf-tab:*' popup-min-size 50 8
# only apply to 'diff'
zstyle ':fzf-tab:complete:diff:*' popup-min-size 80 12

Default Value: 0 0


Swap tab and btab direction when tmux-popup shows above the cursor.

Default value: yes

⚠️ ** Fallback** ⚠️