frank

a Yazi plugin that stitches fzf, fd, rg, rga, bat, and eza together to provide a live search (by name or content) with some preview capabilities

supported shells: bash, fish, and zsh

dependencies

• bat
• eza
• fd
• fzf
• ripgrep
• ripgrep-all

note that fzf is required for the interface, while other dependencies are optional depending on your usage (see "dependencies by usage" section below)

installation

ya pkg add lpnh/frank

usage

Note

experimental API: i'm still figuring out the best defaults and arguments

if you have suggestions for better defaults and/or arguments, feel free to open an issue or start a discussion — opinions are more than welcome

plugin arguments

to avoid ambiguity, this plugin has a two-argument structure, so we can differentiate the search method (by name vs content) and their respective options

for convenience, you can pass only the first argument and let the plugin fall back to a default second argument. these single-argument forms are the content and name aliases listed below

search by content

• content: alias for content rg
• content rg: search using ripgrep
• content rga: search using ripgrep-all

search by name

• name: alias for name all
• name all: search files and directories
• name cwd: search files and directories in the current directory
• name dir: search directories only
• name file: search files only

dependencies by usage

the tables below show what dependencies are required for each usage

search engine

tool	plugin option
ripgrep	content rg
ripgrep-all	content rga
fd	name all, name cwd, name dir, name file

file content preview

tool	plugin option
bat	content rg, name all, name cwd, name file
ripgrep-all	content rga

directory content preview

tool	plugin option
eza	name all, name cwd, name dir

file metadata preview

tool	plugin option
eza	content rg, content rga, name file

directory metadata preview

tool	plugin option
eza	name all, name cwd, name dir

keymaps

minimal config

below is an example of how to configure both searches in the ~/.config/yazi/keymap.toml file, using only the aliases:

[[mgr.prepend_keymap]]
on = ["f", "r"]
run = "plugin frank content"
desc = "Search file by content (rg)"

[[mgr.prepend_keymap]]
on = ["f", "d"]
run = "plugin frank name"
desc = "Search by name, files and dirs (fd)"

full config

below is an example how to configure all the available options:

[[mgr.prepend_keymap]]
on = ["f", "r"]
run = "plugin frank 'content rg'"
desc = "Search file by content (rg)"

[[mgr.prepend_keymap]]
on = ["f", "A"]
run = "plugin frank 'content rga'"
desc = "Search file by content (rga)"

[[mgr.prepend_keymap]]
on = ["f", "a"]
run = "plugin frank 'name all'"
desc = "Search by name, files and dirs"

[[mgr.prepend_keymap]]
on = ["f", "c"]
run = "plugin frank 'name cwd'"
desc = "Search by name, files and dirs (CWD)"

[[mgr.prepend_keymap]]
on = ["f", "d"]
run = "plugin frank 'name dir'"
desc = "Search directory by name"

[[mgr.prepend_keymap]]
on = ["f", "f"]
run = "plugin frank 'name file'"
desc = "Search file by name"

important: before using the examples above, ensure the keybindings don't conflict with your other commands/plugins. feel free to adjust the descriptions

fzf binds

this plugin provides the following custom fzf keybindings:

• alt-p: toggle the preview ("content", "metadata")
• ctrl-o: open selected entry with default editor ($EDITOR)
• ctrl-r: reload the search
• ctrl-s: toggle between fuzzy and exact match for the current query results
• ctrl-]: toggle the preview window size (66%, 80%)
• ctrl-\: toggle the preview window position (top, right)

customization

color themes

fzf

you can customize the default fzf colors using the FZF_DEFAULT_OPTS environment variable. for an example, check out Catppuccin's fzf repo

more examples of color themes can be found in the fzf documentation

eza

you can customize the colors of eza previews using its ~/.config/eza/theme.yml configuration file. check the eza-theme repository for some existing themes

for more details, see eza_colors-explanation

advanced

for those seeking further customization, you can tweak all the integrated tools used by this plugin in your ~/.config/yazi/init.lua file. simply pass a table to the setup function with any of the following fields and their respective options:

require("frank"):setup({
  fzf = "",            -- global fzf options
  -- content search options
  rg = "",             -- ripgrep options
  rga = "",            -- ripgrep-all options
  -- name search options
  fd = "",             -- fd options
  -- preview options
  bat = "",            -- bat options for file preview (rg,fd)
  eza = "",            -- eza options for directory preview (fd)
  eza_meta = "",       -- eza metadata options (rg,rga,fd)
  rga_preview = "",    -- ripgrep-all preview options (rga)
  -- extra preview command
  img_preview = "",    -- image preview command (fd)
})

all fields are optional and accept either a string or a table of strings containing command-line options, except img_preview, which expects a full command rather than option flags

example:

require("frank"):setup {
  fzf = [[--info-command='echo -e "$FZF_INFO 💛"' --no-scrollbar]],
  rg = "--colors 'line:fg:red' --colors 'match:style:nobold'",
  rga = {
    "--follow",
    "--hidden",
    "--no-ignore",
    "--glob",
    "'!.git'",
    "--glob",
    "!'.venv'",
    "--glob",
    "'!node_modules'",
    "--glob",
    "'!.history'",
    "--glob",
    "'!.Rproj.user'",
    "--glob",
    "'!.ipynb_checkpoints'",
  },
  fd = "--hidden",
  bat = "",
  eza = "",
  eza_meta = "--total-size",
  rga_preview = {
    "--colors 'column:fg:black'"
      .. " --colors 'line:fg:black'"
      .. " --colors 'match:fg:black'"
      .. " --colors 'match:bg:blue'"
      .. " --colors 'match:style:nobold'"
      .. [[ --context-separator=" "]]
      .. [[ --field-context-separator=" "]]
      .. [[ --field-match-separator=" "]],
  },
  img_preview = "chafa --size=60x20",
}

extra previews

image (search by name only)

the img_preview field takes a command that will replace the default file preview (bat) for image files

note that image rendering in terminals can be a little tricky. before using this feature, make sure your current environment supports it and the command is properly configured

fzf exposes $FZF_PREVIEW_COLUMNS and $FZF_PREVIEW_LINES environment variables which can be used to set the output image dimensions

important: the FZF_PREVIEW_LINES do not account for the 3 lines used by this plugin to print its custom header. so we need to adjust it accordingly

using chafa, for example, the img_preview entry would look like:

require("frank"):setup {
  img_preview = 'chafa --size="${FZF_PREVIEW_COLUMNS}x$((FZF_PREVIEW_LINES - 3))"',
}

for fish, it becomes:

require("frank"):setup {
  img_preview = 'chafa --size=$FZF_PREVIEW_COLUMNS"x"(math $FZF_PREVIEW_LINES - 3)',
}

hint: ctrl-] and ctrl-\ keybinds can be used to toggle the preview window size and position, respectively

---

almost everything from interface elements to search filters can be customized. you just need to find the right flag