Previews

Previews are off by default. Add a [preview] section to a palette (or to your global config.toml), then set enabled = true. The command starts as soon as the highlighted source item changes. Vellum keeps the previous result visible until the next one arrives, cancels superseded work, and reuses the 50 most recent previews. Output is limited to 128 KiB per command, and slow commands time out.

[preview]
enabled = true
position = "right" # left, right, top, or bottom
# initial_scroll = "bottom" # show the latest output first; default is top
size = 55          # percentage of the results area, 10–90
title = "File"
command = ["bat", "--color=always", "--decorations=always", "--style=numbers", "--line-range=:300", "$path"]
border = "separator" # separator (default), full, none
scrollbar = true    # show a scrollbar when content overflows
scroll_up = "ctrl-u"
scroll_down = "ctrl-d"
timeout_ms = 2000

The command is an argv array, executed directly without a shell. ANSI SGR colors from commands such as bat --color=always are rendered in the preview. An argument that consists entirely of $field or $nested.field resolves to a scalar field on the selected source item; missing fields show an error in the pane. cwd = "$directory" supports the same substitution. Literal arguments remain literal. For shell features, explicitly use command = ["sh", "-c", "...", "sh", "$path"] and reference the selected path as $1 inside the script.

Ctrl-U and Ctrl-D scroll the preview by half a viewport when previews are active; change scroll_up and scroll_down to other bindings if you use those keys for list paging. The mouse wheel scrolls whichever pane it is over: preview or results. The scrollbar appears only when the preview exceeds its viewport. A separator is the default chrome: it draws one line between results and preview. Use border = "full" for a complete box or border = "none" for no chrome. Set item.box_title = "Results" to give the results their own titled box.

initial_scroll = "bottom" starts each new preview at the latest lines, including cached results; omit it to start at the top. This is useful for live pane output. After the preview appears, the usual keys and mouse wheel scroll freely in either direction.

Preview commands receive VELLUM_PREVIEW_WIDTH (available text columns, reserving a column when scrollbars are enabled) and VELLUM_PREVIEW_STYLE (light or dark, based on the active theme background). Previews rerun when width or style changes, and their cache includes both values. For Markdown in a $body field:

[preview]
enabled = true
command = ["sh", "-c", 'printf "%s" "$1" | glow --style "$VELLUM_PREVIEW_STYLE" --width "$VELLUM_PREVIEW_WIDTH" -', "sh", "$body"]

Use --preview to enable a configured preview, --no-preview to hide it, or --preview-position left|right|top|bottom to enable it at that location for one invocation. A preview command must be configured to enable previews. On small terminals the pane disappears automatically so results remain usable. The preview uses your existing theme’s foreground, background, border, and selection colors.

See the files-with-preview example for a complete palette.

Other layouts: framed results and preview and borderless preview.