# How the Superfile Hotkey System Works: Configuring Keybindings in yorukot/superfile

> Learn how Superfile's hotkey system works via declarative TOML config files. Map actions to keys for global, typing, and mode-specific scopes, reloading dynamically without restarts.

- Repository: [Yorukot/superfile](https://github.com/yorukot/superfile)
- Tags: internals
- Published: 2026-07-28

---

**Superfile drives its keyboard shortcuts through a declarative TOML configuration file that maps action names to key combinations, registering them via the Tauri `hotkey` plugin with support for global, typing, and mode-specific scopes that reload dynamically without restarting the application.**

Superfile is a modern terminal-based file manager built with Rust and Tauri. Its keyboard-driven workflow is governed by a flexible configuration system that allows users to remap actions, define multi-key shortcuts, and switch between default and Vim-style layouts by editing simple TOML files.

## Architecture of the Hotkey System

The hotkey system in `yorukot/superfile` operates through a layered architecture that parses user configuration, merges it with built-in defaults, and registers listeners through the Tauri runtime.

### TOML Configuration Parsing

When the application initializes, the core Rust layer reads [`src/superfile_config/hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/hotkeys.toml) using the `toml` crate. This file defines a mapping where each **action name** (such as `list_down` or `copy_items`) corresponds to an array of key strings. The parser validates these entries and constructs an internal map that links UI actions to their trigger keys.

### Tauri Hotkey Plugin Integration

After parsing, each entry is registered with the **Tauri `hotkey` plugin**. This plugin creates native OS-level listeners that fire the associated action callback when the registered combination is pressed. The plugin supports modifier prefixes including `ctrl+`, `shift+`, `alt+`, and recognizes special keys like `enter`, `esc`, `pgdown`, and `backspace`.

### Mode-Based Scoping

Hotkeys are organized into three distinct scopes that determine when they are active:

- **Global hotkeys** – Always active regardless of UI state. These handle navigation and core commands.
- **Typing hotkeys** – Take precedence when the user is focused on an input field. These override all other bindings to ensure text entry works correctly.
- **Mode-specific hotkeys** – Active only when the UI is in a specific mode (e.g., *Normal* vs. *Selection*). These allow context-sensitive commands.

## Configuration File Structure

All keybinding customization centers on two files in the repository root.

### Default Hotkeys Location

The primary configuration file is [`src/superfile_config/hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/hotkeys.toml). This file contains the default mapping used when no user overrides are present. It is organized into sections:

- Global actions (lines 16-73)
- Typing overrides (lines 77-81)
- Mode-specific bindings (lines 84-96)

### Action Definition Syntax

Each binding follows a strict pattern:

```toml
<action_name> = ['<key1>', '<key2>', ...]

```

For example, in [`src/superfile_config/hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/hotkeys.toml):

```toml
list_down = ['down', 'j']
list_up = ['up', 'k']
copy_items = ['ctrl+c', '']
toggle_file_preview_panel = ['f', '']

```

- **`<action_name>`** must match a command recognized by the Superfile core.
- **Keys** use Tauri's syntax: lowercase key names with modifiers separated by plus signs.
- **Empty strings** (`''`) serve as placeholders when only one shortcut is needed.

### Vim-Style Alternative Preset

For users preferring Vim conventions, the repository includes [`src/superfile_config/vimHotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/vimHotkeys.toml). This preset remaps navigation to `h`, `j`, `k`, `l` and adjusts other bindings to follow modal editing patterns. Users can replace the contents of [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) with this file's contents to switch presets.

## Practical Configuration Examples

The TOML-based system supports adding custom shortcuts, overriding specific modes, disabling unwanted bindings, and switching entire layouts.

### Adding Custom Shortcuts

To bind `Ctrl+Shift+S` to the `save_items` action, append the following to [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml):

```toml
save_items = ['ctrl+shift+s', '']

```

Save the file; Superfile's file watcher automatically registers the new shortcut without requiring a restart.

### Overriding Mode-Specific Bindings

To remap the *parent directory* action to use `h` in Normal mode while preserving other modes, locate the Normal Mode section and modify:

```toml

# Normal Mode Actions

parent_directory = ['h', 'left', 'backspace']

```

This change affects only Normal mode, leaving Selection mode and global bindings untouched.

### Disabling Unwanted Hotkeys

To completely disable a shortcut, provide an empty array:

```toml
quit = ['', '']

```

This removes all keybindings for the quit action, preventing accidental triggering.

### Switching to Vim-Style Layouts

To adopt the Vim preset, copy the contents of [`src/superfile_config/vimHotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/vimHotkeys.toml) into your active [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) (or configure the application to load the Vim file directly). After saving, the interface immediately adopts `h`/`j`/`k`/`l` navigation and modal command structures.

## Conflict Resolution and Precedence

When the same key appears in multiple scopes, Superfile resolves conflicts using a strict precedence order: **typing → mode-specific → global**.

If a user presses `ctrl+c` while typing in a search box, the typing scope wins even if `ctrl+c` is also mapped globally to `copy_items`. The configuration also warns about keys that conflict with core terminal controls (such as `ctrl+c` for interrupt signals) in the documentation at `website/src/content/docs/configure/custom-hotkeys.mdx`.

## Dynamic Reloading Behavior

Superfile implements a file watcher on [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml). When the file is modified and saved, the application re-parses the configuration, unregisters obsolete shortcuts from the Tauri plugin, and registers new bindings without terminating the process. This gives immediate feedback during configuration adjustments and eliminates the need to restart the file manager when refining keybindings.

## Summary

- Superfile uses **TOML configuration files** ([`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) and [`vimHotkeys.toml`](https://github.com/yorukot/superfile/blob/main/vimHotkeys.toml)) to define keybindings as mappings between action names and key arrays.
- The **Tauri `hotkey` plugin** registers these as native OS listeners supporting modifiers like `ctrl+`, `shift+`, and `alt+`.
- Three **scopes** control activation: global (always on), typing (input-focused), and mode-specific (context-dependent), with precedence following that order.
- Changes to [`src/superfile_config/hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/hotkeys.toml) are **dynamically reloaded** via file watching, applying immediately without restart.
- Users can **disable shortcuts** with empty arrays, **add custom bindings** with standard TOML syntax, or **switch to Vim-style layouts** by replacing the default file with [`vimHotkeys.toml`](https://github.com/yorukot/superfile/blob/main/vimHotkeys.toml).

## Frequently Asked Questions

### Where are the default keybindings defined in the Superfile source code?

The default keybindings are defined in [`src/superfile_config/hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/hotkeys.toml) within the repository. This file contains global shortcuts, typing overrides, and mode-specific actions. An alternative Vim-style preset is available at [`src/superfile_config/vimHotkeys.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/vimHotkeys.toml).

### What is the syntax for defining a multi-key shortcut in Superfile?

Use a TOML array with Tauri-compatible key strings. For example, `copy_items = ['ctrl+c', '']` assigns `Ctrl+C` to the copy action. Modifiers are written as prefixes (e.g., `ctrl+shift+s`), and empty strings act as placeholders when only one key is needed.

### How does Superfile handle keybinding conflicts between different modes?

Superfile resolves conflicts using a precedence hierarchy: **typing hotkeys override mode-specific hotkeys, which override global hotkeys**. If a key is bound in both the global scope and the typing scope, the typing scope wins when the user is focused on an input field.

### Can I change hotkeys without restarting Superfile?

Yes. Superfile watches the [`hotkeys.toml`](https://github.com/yorukot/superfile/blob/main/hotkeys.toml) file for changes and automatically reloads the configuration when you save edits. The Tauri plugin unregisters old bindings and registers new ones immediately, allowing you to test configuration changes in real-time.