Preview window

--preview '<command>' runs a shell command for the highlighted item and renders its output in a side window. It is fzf's most flexible feature and the basis for many of the third-party tools that wrap fzf.

Anatomy of --preview

fzf --preview 'bat --color=always {}' \
    --preview-window=right:60%:border-rounded \
    --bind 'ctrl-p:change-preview-window(down|hidden|right)'

• --preview '<cmd>' — the command template; placeholders are substituted at run time.
• --preview-window=POS[:SIZE[%]][:OPTS] — placement. right, left, top, bottom, down, up, hidden, nowrap, wrap, cycle, follow, border-*, <+offset>, <+offset/N>, etc.
• --preview-label, --preview-label-pos, --preview-border — labeling and bordering.
• The change-preview action mutates the command at runtime; change-preview-window cycles through layouts.

Placeholder language

The substitution rules are defined by the placeholder regex at the top of src/terminal.go:

\\?(?:{[+*sfr]*[0-9,-.]*}|{q(?::s?[0-9,-.]+)?}|{fzf:(?:query|action|prompt)}|{[+*]?f?nf?})

Placeholder	Meaning
{}	Current item (raw).
{q}	Current query string.
{q:s5} / {q:5}	Substring of the query.
{1}, {2..3}, {-1}	Tokenized field expressions (using --delimiter).
{+}	All multi-selected items, space-separated.
{*}	All visible items.
{f} (e.g. {+f})	Write the value(s) to a temp file and substitute the path; useful when the argument is huge.
{r}	Pass raw without shell-escaping.
{n} (e.g. {+n})	Numeric index of the item, 0-based.
{nf}	File-mode equivalent for n.
{fzf:query}	Synonym of {q}.
{fzf:action}	Name of the action that triggered the substitution.
{fzf:prompt}	Current prompt.
\{...}	Escapes a {...} so it is passed through literally.

Substitution is implemented by replacePlaceholder in src/terminal.go. Multi-selection bracket forms ({+...}) preserve the user's selection order; tokens are extracted via the tokenizer.go parser.

Lifecycle

graph LR
    SELECT[Cursor moves<br/>to new item] --> EVENT[Terminal emits<br/>focus event]
    EVENT --> SUBST[replacePlaceholder<br/>fills in {}, {q}, ...]
    SUBST --> EXEC[Spawn command<br/>util.Executor]
    EXEC --> CAPTURE[Capture stdout chunk-by-chunk]
    CAPTURE --> RENDER[printPreview<br/>src/terminal.go]
    RENDER --> WIN[Preview Window]

The preview command runs asynchronously. If the user moves to a new item before it finishes, fzf kills the previous command (via util.Executor.Kill) and starts a new one. Output is streamed line-by-line so large files start rendering immediately.

Image protocols

src/terminal.go recognizes three "passthrough" escape sequences and forwards them verbatim:

• tmux passthrough (\x1bPtmux;...).
• Sixel (\x1bP[0-9;]*q...).
• Kitty graphics (\x1b_G...).
• iTerm2 image protocol (\x1b]1337;...).

This is what enables previews like chafa, kitty +kitten icat, and imgcat. The detection happens in the per-line writer that feeds the preview window.

Useful actions

These actions are usually paired with --preview:

Action	Effect
change-preview(<cmd>)	Replace the preview command.
change-preview-window(<spec>)	Cycle through layouts; multiple specs separated by | are toggled in order.
toggle-preview	Show/hide the preview pane.
toggle-preview-wrap	Toggle line wrapping.
preview-up / preview-down / preview-page-up / preview-page-down / preview-half-page-up / preview-half-page-down / preview-top / preview-bottom	Scroll the preview.
transform-preview-window(<cmd>)	Compute a new layout from a shell command.
transform-preview-label(<cmd>)	Compute a new label from a shell command.

Useful supporting tools

• bin/fzf-preview.sh — opinionated default preview script that handles directories, code (bat), images (chafa/iTerm), and archives. Use it as --preview 'fzf-preview.sh {}'.
• The man page (man/man1/fzf.1, sections "PREVIEW WINDOW" and "AVAILABLE ACTIONS") is the authoritative reference for all preview-related options.

Where it lives

Concern	File
--preview parsing	src/options.go
Placeholder regex / substitution	src/terminal.go
Tokenizer for {1}, {2..-1}	src/tokenizer.go
Window layout / scrolling	src/terminal.go, src/tui/tui.go
Image protocol passthrough	src/terminal.go (passThroughBeginRegex, passThroughEndTmuxRegex)
Tests	test/test_preview.rb
Default preview script	bin/fzf-preview.sh