33 Configuration

Charles Tamzarian edited this page 2025-06-13 15:53:50 +10:00

Unescape Escape

Table of Contents

• Configuration
• Universal
• fzf-command
• fzf-bindings
• fzf-bindings-default
• fzf-preview
• fzf-flags
• fzf-pad
• fzf-min-height
• accept-line
• continuous-trigger
• print-query
• switch-group
• query-string
• prefix
• default-color
• single-group
• group-colors
• show-group
• disabled-on
• ftb-tmux-popup
• popup-pad
• popup-min-size
• popup-smart-tab

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Configuration

Universal

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

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

The basic format of the command is zstyle ':fzf-tab:{context}' tag value. :fzf-tab: is the top-level context, distinct from the default :completion: in zsh's completion system.

You can take a look at zsh's doc for more information about zstyle.

To get possible context for a command, you can use C-x h.

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 the available tags in fzf-tab context:

fzf-command

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

Specify the fuzzy search program.

By default, fzf-tab use the original 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.

Tip

ftb-tmux-popup can also be used as a general fzf wrapper, eg fc -rl 1 | ftb-tmux-popup -n "2.." --tiebreak=index --prompt="cmd> "

fzf-bindings

It can be used to append 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")'

fzf-bindings-default

Overriden fzf-tab's default bindings

fzf-preview

The code for previewing.

For more information about previewing, please see Preview

fzf-flags

Any extra flags for the 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: None

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.

There are four options for zstyle ':fzf-tab:*' show-group:

1. full to show all descriptions
2. brief to only show descriptions for groups with duplicate members, replacing other ${group} values with __hide__.
3. none to show no headers and replace all ${group} values with __hide__
4. quiet to show no headers while still providing the original ${group} value(s) for use in FZF preview/shell commands -- see #518 for details

Note that for the first three options, when a description header is not shown, its ${group} preview variable is set to a value of __hide__.

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 'eza -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

Note

• The default value (yes) prevents binding tab and shift-tab (btab)
• You can disable with: zstyle ':fzf-tab:*' popup-smart-tab no