Skip to main content

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.

​
Introduction

Yazi provides a powerful Lua plugin API that allows you to extend and customize its functionality. Plugins can be used for:
  • Custom file previewers
  • File operations and automation
  • UI components and themes
  • Integration with external tools
  • Custom actions and keybindings

​
Lua Version

Yazi uses Lua 5.5 as of version 0.4.0 (upgraded from Lua 5.4). This upgrade brings performance improvements through external strings, reducing memory allocations.
Lua 5.5 introduces external strings for better memory efficiency. See #3633 for details.

​
API Namespaces

The plugin API is organized into several global namespaces:

​
Core APIs

  • ya - Core Yazi API for async operations, sync blocks, logging, and utilities
  • fs - Filesystem operations (copy, rename, read_dir, etc.)
  • ui - UI rendering components and helpers
  • ps - Publish/Subscribe messaging system
  • cx - Context API for accessing application state

​
Configuration APIs

  • rt - Runtime configuration (args, mgr, preview, tasks, etc.)
  • th - Theme colors and styling

​
Async Support

Yazi’s plugin system supports asynchronous operations through Lua coroutines:

​
Module-level Async

Plugins can use the @sync annotation to declare async entry points: 
--- @sync peek
local M = {}

function M:peek(job)
  -- This function runs in sync context
  -- Can call async APIs directly
  local cha, err = fs.cha(job.file.url)
end

return M

​
Runtime Async

For dynamic async operations, use ya.async(): 
local handle = ya.async(function()
  -- Async code here
  local files = fs.read_dir(Url("/path"), { limit = 100 })
end)

​
Sync Blocks

Use ya.sync() to execute code in the main thread with access to the plugin context: 
local config = ya.sync(function()
  return plugin.config
end)

​
Plugin Types

Yazi supports several types of plugins:

​
Previewers

Generate file previews for the preview pane: 
function M:peek(job)
  local cha = fs.cha(job.file.url)
  if not cha then
    return
  end
  
  ya.preview_widget(job, ui.Text("Preview content"):area(job.area))
end

​
Preloaders

Load file metadata in the background: 
function M:preload(job)
  local cache = ya.file_cache(job)
  if cache then
    return 1  -- Already cached
  end
  
  -- Load and cache data
  return 2  -- Fully loaded
end

​
Actions

Custom user actions triggered by keybindings: 
function entry()
  local h = cx.active.current.hovered
  if h then
    ya.manager_emit("open", { h.url })
  end
end

​
Init Plugins

Run on startup from init.lua: 
-- ~/.config/yazi/init.lua
require("custom-plugin"):setup()

​
Error Handling

Most async APIs return (result, error) tuples: 
local cha, err = fs.cha(url)
if not cha then
  ya.err("Failed to get metadata: " .. tostring(err))
  return
end
Create custom errors: 
local err = Error.custom("Something went wrong")
return nil, err

​
Data Types

Common userdata types:
  • Url - File/directory URL (local or remote)
  • Path - Local filesystem path
  • File - File metadata and attributes
  • Cha - File characteristics (size, permissions, etc.)
  • Rect - Screen rectangle (x, y, w, h)
  • Id - Unique identifier

​
Best Practices

  1. Use async APIs - Most filesystem operations are async for better performance
  2. Handle errors - Always check error returns from async functions
  3. Cache data - Use ya.file_cache() for expensive operations
  4. Limit resources - Use options like limit in fs.read_dir() to avoid loading too much data
  5. Clean up - Drop file descriptors and handles when done using ya.drop()

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us