Configuration

Universal

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:

NOTE:

• 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:

fzf-command

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

fzf-bindings

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.

Example:

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

fzf-preview

The code for previewing.

For more information about previewing, please see Preview

fzf-flags

Any extra flags for fzf-command.

Default value: None

fzf-pad

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

fzf-min-height

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

Default value: 0

accept-line

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

Example:

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

Default value: None

continuous-trigger

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.

print-query

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-group

Switch over different groups (#183).

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

query-string

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

prefix

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.

default-color

Color when there is no group.

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

single-group

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

group-colors

Color for different groups and their descriptions.

Default value:

FZF_TAB_GROUP_COLORS=(
    $'\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
        colors+=("%F{$i}$i%f")
    done
    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}}
}

show-group

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

disabled-on

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.

Allowlist:

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

Denylist:

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

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

ftb-tmux-popup

popup-pad

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

popup-min-size

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

Example:

# 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

popup-smart-tab

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

Default value: yes