Popup modes

fzf can render in three different "container" modes besides the default fullscreen TUI. Each one wraps the regular fzf.Run event loop in a different surrounding terminal.

--height [-]N[%]

The simplest mode. Instead of taking the entire terminal, fzf draws into the bottom (or top, with --layout=reverse-list and similar) N rows of the current screen. After exit, fzf clears its area and the shell prompt is right back where it was.

• Adaptive form: --height ~50% resizes based on the actual number of items (up to 50%).
• Negative form: --height=-3 reserves 3 rows for the rest of the terminal.
• Combine with --layout=reverse and --border for a polished prompt-like UI.

Implementation: the Renderer interface in src/tui/tui.go knows how to allocate a sub-area; Terminal.Loop checks opts.Height and the fitpad machinery in core.go decides when to start drawing (after EvtSearchFin so it knows the content).

--tmux [POS][,SIZE[%]][,SIZE[%]][,border-native]

Pops fzf in a tmux display-popup floating window. Requires tmux 3.3+.

--tmux                          # default: center, 50% x 50%
--tmux center,80%,80%
--tmux up,40%
--tmux right,50%,80%,border-native

Implementation: runTmux in src/tmux.go builds the appropriate tmux display-popup -E -d <dir> -x.. -y.. -w.. -h.. sh /tmp/... command and delegates to runProxy in src/proxy.go. See systems/process-modes.

--popup (Zellij)

Equivalent to --tmux, but for Zellij's floating panes. Requires Zellij 0.44+. Implementation in src/zellij.go.

bin/fzf-tmux (legacy)

A bash script that predates the in-binary --tmux and pops fzf in a regular tmux split (rather than a floating popup). Still useful for users on tmux < 3.3 and for compatibility with old setups.

fzf-tmux             # 40% bottom split
fzf-tmux -p          # popup, requires tmux 3.3+
fzf-tmux -d 40%      # bottom split, 40% of screen
fzf-tmux -u 40%      # top split
fzf-tmux -l 40%      # left split
fzf-tmux -r 40%      # right split

It is processed by shell/update.sh like the other shell scripts (so its common.sh includes stay in sync).

How they compose

You can mix them: shell key bindings (__fzfcmd in shell/key-bindings.bash) auto-detect tmux and route through fzf-tmux if FZF_TMUX=1 (or FZF_TMUX_OPTS is set). Inside fzf-tmux or --tmux, the embedded fzf process re-execs with --no-popup --no-height so the user's options don't recompose unintentionally.

--margin and --padding

Independent of popup mode but often used with it: extra empty space outside (--margin) and inside (--padding) the picker. The Style system (--style=default|minimal|full[:BORDER_STYLE]) is the modern way to set both at once.

Where it lives

Concern	File
--height	src/options.go, src/core.go (fitpad), src/terminal.go
--tmux	src/tmux.go, src/proxy.go
--popup (Zellij)	src/zellij.go, src/proxy.go
fzf-tmux script	bin/fzf-tmux
Tests	test/test_layout.rb, test/test_core.rb