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

> Understand the fzf --height and --tmux display modes. Learn how --height renders fzf below the cursor and --tmux creates a tmux popup for a better workflow.

- Repository: [Junegunn Choi/fzf](https://github.com/junegunn/fzf)
- Tags: deep-dive
- Published: 2026-03-01

---

**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`](https://github.com/junegunn/fzf/blob/main/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.

```bash

# 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`](https://github.com/junegunn/fzf/blob/main/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.

```bash

# 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`](https://github.com/junegunn/fzf/blob/main/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.

```bash

# 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`](https://github.com/junegunn/fzf/blob/main/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`](https://github.com/junegunn/fzf/blob/main/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.