# How to Integrate Superfile with Zoxide for Smart Directory Navigation

> Supercharge your workflow! Integrate Superfile with zoxide for lightning-fast, fuzzy directory jumping. Enable zoxide support and navigate your file system with ease.

- Repository: [Yorukot/superfile](https://github.com/yorukot/superfile)
- Tags: how-to-guide
- Published: 2026-07-26

---

**Superfile ships with a built-in zoxide plugin that enables fuzzy directory jumping via a searchable modal when you enable the `zoxide_support` configuration flag and press the `z` key.**

Superfile is a modern terminal file manager written in Go that supports plugin-based extensibility. You can integrate superfile with zoxide to replace manual directory traversal with intelligent, frequency-based directory jumping directly inside your file manager. This integration leverages the `github.com/lazysegtree/go-zoxide` library to query your zoxide database and render results in a native modal window.

## Enable Zoxide Support in the Configuration

Before using the navigation features, you must activate the plugin in Superfile’s global configuration. The `zoxide_support` boolean flag lives in **[`src/superfile_config/config.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/config.toml)** at line 170.

Set the value to `true` to initialize the zoxide client:

```toml

# src/superfile_config/config.toml

zoxide_support = true   # Requires the external `zoxide` binary installed on your system

```

When this flag is enabled, Superfile loads the zoxide UI component at runtime and creates a client instance that connects to your local zoxide database (typically located at `~/.local/share/zoxide`).

## Trigger the Navigation Modal

Once enabled, open the zoxide search interface using the default hotkey binding defined in **[`src/superfile_config/hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/hotkeys.toml)** (line 69):

- Press **`z`** in the Superfile UI to dispatch the `open_zoxide` command.

This opens a modal titled "Zoxide Navigation" where you can type partial directory names. The modal queries the database live and presents fuzzy-matched results. Use the arrow keys to select an entry and press **Enter** to execute a `ChangeDir` action, which instantly switches Superfile’s working directory to the selected path.

## How the Integration Works Under the Hood

The integration follows a clean three-layer architecture that separates configuration, state management, and rendering.

### The Model and Client Initialization

The core state container resides in **[`src/internal/ui/zoxide/model.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/zoxide/model.go)** (lines 10–22). This file defines a `Model` struct that holds a pointer to the `*zoxidelib.Client`, the current query string, and the result list:

```go
// Conceptual structure from src/internal/ui/zoxide/model.go
type Model struct {
    client    *zoxidelib.Client
    query     string
    results   []Result
    // ... other UI state fields
}

```

The `GenerateModel` function initializes this structure with your terminal dimensions and a pre-configured zoxide client.

### Input Handling and Database Queries

Keyboard events are processed in **[`src/internal/ui/zoxide/navigation.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/zoxide/navigation.go)**. This handler forwards your typed query to the Go zoxide library and updates the model’s result slice with matching directories and their frequency scores.

When you press Enter on a selection, the navigation layer returns a message that triggers the directory change in Superfile’s core model.

### Rendering and Modal Validation

The visual output is drawn by **[`src/internal/ui/zoxide/render.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/zoxide/render.go)**. If the zoxide binary is missing or the database is inaccessible, lines 22–31 display a helpful error message instead of crashing. The modal respects Superfile’s global UI state; **[`src/internal/validation.go`](https://github.com/yorukot/superfile/blob/main/src/internal/validation.go)** (line 427) ensures the zoxide window only opens when no other modal (help menus, prompts, or dialogs) is currently active.

## Customize the Hotkey Binding

If the default `z` key conflicts with your workflow, remap the trigger in **[`src/superfile_config/hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/hotkeys.toml)**:

```toml

# src/superfile_config/hotkeys.toml

open_zoxide = ['x', '']   # Now pressing `x` opens the zoxide modal

```

You can assign any single character or an empty string to disable the binding entirely.

## Summary

- **Enable the plugin** by setting `zoxide_support = true` in [`src/superfile_config/config.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/config.toml).
- **Trigger the modal** with the `z` key (or your custom binding) mapped to `open_zoxide` in [`src/superfile_config/hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/hotkeys.toml).
- **Architecture** relies on [`src/internal/ui/zoxide/model.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/zoxide/model.go) for state, [`navigation.go`](https://github.com/yorukot/superfile/blob/main/navigation.go) for input handling, and [`render.go`](https://github.com/yorukot/superfile/blob/main/render.go) for display.
- **Safety checks** in [`src/internal/validation.go`](https://github.com/yorukot/superfile/blob/main/src/internal/validation.go) prevent modal conflicts, while [`render.go`](https://github.com/yorukot/superfile/blob/main/render.go) handles missing zoxide binaries gracefully.
- **Database access** occurs through `github.com/lazysegtree/go-zoxide` querying `~/.local/share/zoxide`.

## Frequently Asked Questions

### Do I need to install zoxide separately to use this integration?

Yes. The `zoxide_support` flag in Superfile requires the external `zoxide` binary to be installed on your system and available in your PATH. Superfile uses the `github.com/lazysegtree/go-zoxide` Go library to interface with the zoxide database, but it does not bundle the underlying zoxide tool itself.

### Can I change the default hotkey for opening the zoxide modal?

Yes. Edit the `open_zoxide` entry in **[`src/superfile_config/hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/hotkeys.toml)** to assign any key you prefer. For example, setting `open_zoxide = ['f', '']` binds the modal to the `f` key instead of the default `z`.

### What happens if I press the zoxide hotkey but the feature is disabled?

If `zoxide_support` is set to `false` (the default), pressing the assigned hotkey will have no effect because the command dispatcher only registers the `open_zoxide` action when the configuration flag is `true`. If the flag is enabled but zoxide is not installed, **[`src/internal/ui/zoxide/render.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/zoxide/render.go)** displays a user-friendly error message indicating that the zoxide binary is missing.

### How does Superfile handle concurrent modal states?

Superfile prevents the zoxide modal from opening if another modal is already active. According to the validation logic in **[`src/internal/validation.go`](https://github.com/yorukot/superfile/blob/main/src/internal/validation.go)** at line 427, the application checks the global UI state before dispatching the `open_zoxide` command, ensuring that help menus, confirmation prompts, or other overlays remain in focus until dismissed.