fzf `--height` vs `--tmux` Display Modes: Key Differences Explained

Use --height to render fzf inside your current terminal below the cursor, and --tmux to spawn a tmux popup pane that overlays your session; when not running inside tmux, --tmux silently falls back to --height behavior.

The junegunn/fzf fuzzy finder offers two distinct display modes for rendering its interactive UI. While both control the vertical space occupied by fzf, they differ fundamentally in where the interface appears and how they interact with your terminal environment.

How --height Works

The --height option renders fzf directly within your current terminal session, positioning the interface below the current cursor line. This mode works universally across any POSIX-compliant terminal without external dependencies.

In src/options.go, the --height argument is parsed by the parseHeight function, which handles the optional ~ prefix (adaptive height) and % suffix. The parsed value is stored in opts.Height and later used to calculate the exact number of rows fzf may occupy.

# Open fzf using 40% of the terminal height below the cursor

seq 1 200 | fzf --height 40% --border --layout reverse

# Adaptive height: shrink to fit content, up to 100% of screen

seq 1 3 | fzf --height ~100%

How --tmux Works

The --tmux option creates a tmux popup pane using tmux's display-popup command (requires tmux ≥ 3.3). Unlike --height, this renders fzf in a separate floating pane that overlays your current tmux window, allowing independent positioning at center, top, bottom, left, or right.

In src/options.go, the parseTmuxOptions function handles the --tmux argument, constructing a TmuxOption struct that records placement, width, height, and whether a native border is requested.

# Open a bottom-aligned popup 80% wide and 40% tall

seq 1 1000 | fzf --tmux bottom,80%,40% --border

Key Differences and Fallback Behavior

Feature	--height	--tmux
Environment	Any terminal	tmux session only
Rendering	Current terminal buffer	New tmux popup pane
Positioning	Fixed below cursor	Configurable (center, edges)
Fallback	None (always works)	Silently ignored if not in tmux

According to the README.md documentation, --tmux is silently ignored when you are not running inside tmux. In practice, this means you can combine both options safely: when inside tmux you get the popup, and when outside you fall back to the --height behavior.

# Graceful fallback: popup in tmux, height mode otherwise

export FZF_DEFAULT_OPTS='--height 40% --tmux bottom,40% --layout reverse --border top'

Implementation Details in Source Code

The display mode logic resides primarily in src/options.go:

• parseHeight (lines 33-41): Parses the --height argument, handling percentage values, the ~ prefix for adaptive sizing, and negative integers (screen height minus N lines).
• parseTmuxOptions (lines 30-38): Parses the --tmux argument into a structured TmuxOption containing placement, width, height, and border settings.

For environments where the built-in --tmux support is unavailable, the repository includes bin/fzf-tmux, a shell script wrapper that implements similar popup functionality using legacy tmux commands.

Summary

• --height renders fzf inline below your cursor in any terminal, with support for fixed percentages, adaptive sizing (~), or negative offsets.
• --tmux spawns a floating tmux popup with independent positioning and dimensions, but only activates inside an active tmux session.
• When both flags are set, tmux users see the popup while non-tmux users automatically fall back to the height-based display.
• Both options are parsed in src/options.go via parseHeight and parseTmuxOptions respectively.

Frequently Asked Questions

What happens if I use --tmux outside of a tmux session?

The option is silently ignored and fzf falls back to either fullscreen mode or the --height specification if you provided one. This is documented in the README: "--tmux is silently ignored when you're not on tmux."

Can I use --height and --tmux together?

Yes, and this is the recommended pattern for portable configurations. When combined, tmux users get the popup display while non-tmux users get the inline height-based window. The fallback happens automatically based on the environment.

How do I position a tmux popup at the top of the screen?

Use the top placement specifier in the --tmux argument: fzf --tmux top,80%,40%. The syntax is --tmux <position>[,<width>][,<height>][,border-native], where position can be center, top, bottom, left, or right.

Which option should I use for SSH sessions?

Use --height for SSH sessions unless you are explicitly running tmux on the remote host. Since --tmux requires an active tmux session to function, --height provides reliable behavior across all terminal environments without dependencies on the window manager.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}