> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sxyazi/yazi/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin System Overview

> Learn about Yazi's powerful Lua-based plugin system for extending functionality

Yazi features a powerful plugin system built on Lua, allowing you to extend and customize every aspect of the file manager. Plugins can add new functionality, customize the UI, preview files, and fetch metadata.

## Plugin Types

Yazi supports four main types of plugins:

### 1. UI Plugins (Components)

UI plugins customize the visual interface by overriding built-in components:

* **Header** - Top bar showing current directory and status
* **Status** - Bottom bar with file info and position
* **Entity** - Individual file/folder rendering
* **Tab** - Tab content area
* **Tabs** - Tab bar
* And more...

UI plugins allow you to completely redesign Yazi's appearance and layout.

### 2. Functional Plugins

Functional plugins add new commands and behaviors:

* Interactive commands (e.g., `zoxide` for directory jumping)
* Batch operations (e.g., `extract` for archive extraction)
* Integration with external tools (e.g., `fzf` for fuzzy finding)
* Custom file operations

These plugins typically have an `entry()` function that executes when called.

### 3. Previewers

Previewer plugins generate file previews in the preview pane:

* **Text/Code** - Syntax highlighting for code files
* **Images** - Display images inline
* **Videos** - Extract and show video thumbnails
* **Archives** - List archive contents
* **PDFs** - Convert PDF pages to images
* **Folders** - Show folder contents

Previewers implement `peek()`, `seek()`, and optionally `preload()` methods.

### 4. Fetchers

Fetcher plugins retrieve file metadata asynchronously:

* **MIME types** - Detect file types
* **Git status** - Show version control info
* **File metadata** - Extract custom properties

Fetchers implement a `fetch()` method that processes files in batches.

### 5. Spotters

Spotter plugins provide detailed file information in the info panel:

* Show file properties and metadata
* Display image dimensions and format
* Video codec and duration info
* Custom file analysis

Spotters implement a `spot()` method that returns formatted data.

## Plugin Configuration

Plugins are configured in `yazi.toml` under the `[plugin]` section:

```toml theme={null}
[plugin]
fetchers = [
  { id = "mime", url = "*/", run = "mime.dir", prio = "high" },
  { id = "mime", url = "local://*", run = "mime.local", prio = "high" },
]

spotters = [
  { url = "*/", run = "folder" },
  { mime = "text/*", run = "code" },
  { mime = "image/*", run = "image" },
  { mime = "video/*", run = "video" },
]

preloaders = [
  { mime = "image/*", run = "image" },
  { mime = "video/*", run = "video" },
  { mime = "application/pdf", run = "pdf" },
]

previewers = [
  { url = "*/", run = "folder" },
  { mime = "text/*", run = "code" },
  { mime = "image/*", run = "image" },
  { mime = "video/*", run = "video" },
  { mime = "application/pdf", run = "pdf" },
  { mime = "application/{zip,rar,7z*,tar,gzip}", run = "archive" },
]
```

### Plugin Matching

Plugins can be matched by:

* **URL patterns** - `url = "*/*.jpg"`, `url = "*/"`
* **MIME types** - `mime = "image/*"`, `mime = "text/*"`
* **Priority** - `prio = "high"` (for fetchers)

## Plugin Location

Plugins are stored in:

* **Linux/macOS**: `~/.config/yazi/plugins/`
* **Windows**: `%APPDATA%\yazi\config\plugins\`

Yazi also includes preset plugins in its installation directory.

## Plugin Structure

Each plugin is a directory or single `.lua` file:

```
plugins/
├── my-plugin/
│   ├── init.lua          # Main plugin file
│   └── utils.lua         # Helper modules
└── simple-plugin.lua     # Single-file plugin
```

For directory-based plugins, Yazi loads `init.lua` by default.

## Calling Plugins

### From keymap.toml

Bind plugins to keys:

```toml theme={null}
[[manager.prepend_keymap]]
on = [ "z" ]
run = "plugin zoxide"
desc = "Jump to directory with zoxide"

[[manager.prepend_keymap]]
on = [ "f" ]
run = "plugin fzf"
desc = "Fuzzy find files"
```

### From Command Line

Call plugins with arguments:

```bash theme={null}
ya pub extract /path/to/archive.zip
```

### From Other Plugins

Plugins can call each other:

```lua theme={null}
-- Call another plugin
ya.emit("plugin", { "plugin-name", arg1, arg2 })

-- Require shared code
local utils = require("my-utils")
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Creating Plugins" icon="code" href="plugins/creating-plugins">
    Learn how to create your own plugins
  </Card>

  <Card title="UI Plugins" icon="palette" href="plugins/ui-plugins">
    Customize Yazi's appearance
  </Card>

  <Card title="Functional Plugins" icon="bolt" href="plugins/functional-plugins">
    Add new commands and behaviors
  </Card>

  <Card title="Previewers" icon="eye" href="plugins/previewers">
    Create custom file previewers
  </Card>

  <Card title="Fetchers" icon="download" href="plugins/fetchers">
    Build metadata fetchers
  </Card>
</CardGroup>