Overview

This chapter shows how fzf adds context without changing the candidate record: previews interpret the focused item, placeholders select fields, and `--with-nth` or `--accept-nth` separate display from handoff. It then follows the selector into Bash, Zsh, Fish, Nushell, Vim, Neovim, tmux, and Zellij, where adapters preserve host syntax and lifecycle. Execution modes such as `execute` and `become` decide whether fzf resumes or hands control away.

Learning outcomes

A preview adds contextual evidence beside a candidate; it does not become a second producer or change the record's domain meaning.
Placeholders and field transformations can show rich context while sending only the fields a consumer expects.
Shell, editor, and multiplexer adapters preserve the core selector role but must respect host syntax, versions, and window lifecycle.

Keywords

fzfpreviewsplaceholdersadaptersshellseditors

Context and Integration Without Losing the Core

A selected row is often only the beginning of a useful terminal action. The person may need to see the matching file line, preserve an identifier hidden inside a formatted record, return to the list after an inspection, or hand the choice to an editor or shell without breaking its syntax. This chapter focuses on how fzf adds that context and reaches different interfaces while keeping the same source–selector–consumer contract. The practical judgment is to add only the preview, transformation, execution mode, and adapter behavior that the data and destination can actually support.

Context without changing the record

A preview is fzf's most direct way to add meaning to a candidate. The candidate remains in the list; an external command receives the current item, and its output appears in a separate preview window. For a file list, that command might show contents. For a search result, it might open the file at the matching line. For a process or pod, it might show a detail view or a log. The preview is therefore contextual evidence alongside the selection, not a second candidate source.

That distinction keeps the producer's responsibility intact. A file producer still decides which paths enter the list. fzf still decides which path has focus. The preview command interprets that path for the person's inspection. If the candidate is instead a process row or a number, a file-oriented preview is the wrong adapter. The project explicitly warns against placing a file-specific preview in global defaults, because fzf is a general-purpose filter and may be fed arbitrary input. A preview belongs with the workflow whose producer guarantees the assumptions it needs.

The preview window can be treated as part of the interaction rather than a fixed decoration. fzf can place it above, below, left, right, or next to the input area; hide it until requested; wrap or follow long output; scroll it; and change its size or layout through a binding. Its command can receive the current record and environment describing the preview's dimensions and position. A long-running preview can render partial output, and a follow mode can keep the view at the end of a growing log. These capabilities make context responsive, but they also mean the child command is part of the latency and resource behavior of the interface.

A structured search result shows how preview and fields work together. Imagine a producer emitting a path, a line number, and matching text separated by colons. The list can search the text field while displaying the path and line number. When the person focuses a row, the preview command can extract the path and line number, show the relevant source, and position the matching line near the middle of the preview. On acceptance, the workflow can open the same path at the same line. fzf did not understand source code; it carried the fields from the producer through a human decision and into two consumers—a preview command and an editor.

Placeholder expressions make that handoff more precise. The ordinary {} placeholder represents the current line and is quoted for use as a command argument. Field expressions such as {1} or {2} select parts of a delimiter-separated record. A + form represents selected items, which matters in multi-select mode, while a * form represents all matched items. Query and ordinal placeholders can carry the current search text or an item's position. For large collections, a file form can place the evaluated list in a temporary file instead of expanding it into a command line whose length may exceed the operating system's argument limit.

Published by DeepMox

FAQ

How does an fzf preview differ from its candidate source?

An fzf preview interprets the focused candidate and shows contextual output beside the list; it does not generate or replace the candidate source.

How should fzf pass a selection to an editor or shell?

fzf should pass the fields the editor or shell expects, using quoted placeholders and explicit field transformations when display context differs from machine input.

When should fzf use `execute` instead of `become`?

Use fzf `execute` when the selector should run a command and remain available, and `become` when acceptance should replace fzf with the selected process.

Previous9 minfzf Live Views and Reloads

Next11 minfzf Workflow Design Principles

fzf Previews and Host Integrations

Context and Integration Without Losing the Core

Context without changing the record

FAQ