Yazi Navigation with fzf and zoxide

Yazi integrates with two powerful fuzzy-finding tools: fzf (general fuzzy finder) and zoxide (smart directory jumper). Understanding the difference between z and Z keybindings is key to efficient navigation.

The Two Navigation Commands

Understanding z (lowercase) - fzf Integration

What It Does

• Triggers fzf (fuzzy finder) to search through the current directory
• Can find both files and directories
• If you select a directory, Yazi changes to it
• If you select a file, Yazi reveals it (navigates to parent directory and highlights the file)

How fzf Works

fzf is a general-purpose fuzzy finder that searches through a list of items in real-time:

1. Live filtering: As you type, it narrows down matches
2. Fuzzy matching: You don't need exact spelling (e.g., mtch finds match)
3. Interactive UI: Arrow keys to navigate, Enter to select
4. Scope: Only searches within the current directory and subdirectories

Example Usage

bash
# In Yazi, press 'z'
# Type partial path or filename
"maze/comp"  → Finds "midimaze/Computer Tech"
"ghost"      → Finds "Ghostty Tab Management.md"

Understanding Z (uppercase/Shift+z) - zoxide Integration

What It Does

• Triggers zoxide to jump to frequently/recently visited directories
• Directories only - cannot reveal files
• Searches your entire frecency database (frequency + recency)
• Works from anywhere in your filesystem

How zoxide Works

zoxide is a smarter cd that learns from your navigation habits:

1. Frecency algorithm: Tracks both how often AND how recently you visit directories
2. Intelligent ranking: Most relevant directories appear first
3. Fuzzy matching: Partial matches work (e.g., maze → /path/to/midimaze)
4. Global scope: Works across your entire filesystem, not just current directory

The Frecency Database

zoxide maintains a database of directories you've visited:

bash
# View your zoxide database
zoxide query --list

# Sample output (ranked by frecency):
/Users/you/Code/github.com/yourname
/Users/you/Code/github.com/yourname/midimaze
/Users/you/Documents
/Users/you/Downloads

Higher in the list = visited more frequently/recently.

Example Usage

bash
# In Yazi, press 'Z' (Shift+z)
# Type partial directory name from ANYWHERE
"maze"    → Jumps to ~/Code/github.com/theslyprofessor/midimaze
"down"    → Jumps to ~/Downloads
"swc"     → Jumps to midimaze/_Nakul/3. SWC Actions

Why Z (Shift+z) Might Not Show Everything

Expected Behavior

Z only shows directories from your zoxide database. If you don't see results:

1. Directory hasn't been visited: zoxide only knows about directories you've cd'd into
2. Fresh install: zoxide database might be empty or sparse
3. Different tool: You're expecting fzf behavior (which shows files + subdirectories)

Building Your zoxide Database

zoxide learns as you navigate:

bash
# In your shell (not Yazi), navigate to directories
cd ~/Code/github.com/theslyprofessor/midimaze
cd ~/Documents
cd ~/Downloads

# These visits are now in zoxide's database
# Next time you use 'Z' in Yazi, these will appear

Comparison: When to Use Each

Use z (fzf) When:

• ✅ Searching within current directory tree
• ✅ Need to find a specific file (not just directories)
• ✅ Exploring unfamiliar directory structures
• ✅ Want to see all subdirectories at once

Use Z (zoxide) When:

• ✅ Jumping to frequently visited directories across your system
• ✅ Quick navigation to known locations
• ✅ Working in deeply nested directory structures
• ✅ Want context-aware, "smart" directory jumping

Integration Architecture

Your Setup

bash
# .zshrc configuration
eval "$(zoxide init zsh)"  # Enables zoxide in shell

# Yazi automatically detects:
# - fzf (if installed) for 'z' command
# - zoxide (if installed) for 'Z' command

What Happens Under the Hood

When you press z in Yazi:

1. Yazi spawns fzf with current directory as input
2. fzf presents interactive fuzzy-finding UI
3. You select result → Yazi navigates or reveals

When you press Z in Yazi:

1. Yazi calls zoxide query --list (or equivalent)
2. zoxide returns ranked directory list based on frecency
3. Presents selection UI (likely using fzf for display)
4. You select result → Yazi changes directory

Searching File Contents (Custom Keybinds)

The default z and Z only search filenames and directory names. To search inside files, you need custom keybinds.

Setup Required

Create ~/.config/yazi/keymap.toml:

toml
[manager]
prepend_keymap = [
  # Search file CONTENTS in current directory (Shift+F)
  { on = "F", run = '''
    shell 'rg --line-number --no-heading --color=always . "$@" 2>/dev/null | \
      fzf --ansi \
          --delimiter ":" \
          --preview "bat --color=always --highlight-line {2} {1} 2>/dev/null" \
          --preview-window "right,60%,border-left,+{2}+3/3" \
          --bind "enter:become(nvim {1} +{2})"' --block --confirm
  ''', desc = "Search file contents (ripgrep + fzf)" },

  # Interactive live ripgrep search (Ctrl+F)
  { on = "<C-f>", run = '''
    shell 'fzf --disabled --ansi \
      --bind "start:reload:rg --column --color=always --smart-case {q} . \"$@\" || :" \
      --bind "change:reload:rg --column --color=always --smart-case {q} . \"$@\" || :" \
      --delimiter : \
      --preview "bat --style=full --color=always --highlight-line {2} {1}" \
      --preview-window "right,60%,border-left,+{2}+4/3" \
      --bind "enter:become(nvim {1} +{2})"' --block --confirm
  ''', desc = "Live ripgrep search (interactive)" },
]

Content Search Keybinds

How F (Shift+F) Works

1. Press F in Yazi
2. ripgrep searches all file contents in current directory
3. fzf displays results with line numbers
4. Type to filter matches
5. Enter opens file in nvim at the matching line

How Ctrl+F Works

1. Press Ctrl+F in Yazi
2. Start typing your search query
3. Results update live as you type (like VS Code search)
4. Enter opens file in nvim at the matching line

Shell Alternatives

If you're in the terminal (not Yazi), use these functions from your zsh config:

bash
# Find in files - search contents, open in nvim
fif [directory]    # Defaults to current dir

# Live ripgrep - interactive search with live results
rfv [initial query]

Additional Navigation Shortcuts

Beyond z and Z, Yazi offers other quick navigation:

Troubleshooting

"Z doesn't show my directories"

Solution: Build your zoxide database by navigating in your shell:

bash
# Navigate to important directories
cd ~/Code/github.com/theslyprofessor/midimaze
cd ~/Documents
cd ~/Downloads

# Or use 'zi' (zoxide interactive) to explore
zi

"z shows too many results"

Solution: Be more specific in your fuzzy search:

bash
# Instead of just "m"
"maze/comp"  # More specific = fewer matches

"Neither z nor Z work"

Check installations:

bash
which fzf      # Should return /opt/homebrew/bin/fzf (or similar)
which zoxide   # Should return /opt/homebrew/bin/zoxide (or similar)

Related Tools

• fzf - General-purpose fuzzy finder (powers z in Yazi)
• zoxide - Smarter cd command (powers Z in Yazi)
• Yazi - Terminal file manager with built-in fuzzy navigation
• ripgrep - Fast file content search (used in Yazi's s command)

Links

Official Documentation

• fzf GitHub: https://github.com/junegunn/fzf↗
• zoxide GitHub: https://github.com/ajeetdsouza/zoxide↗
• Yazi Quick Start: https://yazi-rs.github.io/docs/quick-start↗
• Summary: Official documentation for the fuzzy-finding tools integrated with Yazi

Yazi Keybindings Reference

• URL: https://yazi-rs.github.io/docs/configuration/keymap↗
• Summary: Complete keybinding documentation including navigation commands
• Related: Ghostty Tab Management, Terminal Navigation