Utility API (ya)

The ya global provides all utility functions for plugin development — I/O, IPC, UI, and system operations.

---

File & Cache

ya.file_cache(url) -> Path

Resolve the file preview cache path for a given URL.

local cache = ya.file_cache(file.url)

ya.image_show(url, rect) -> bool

Display an image in the given rect area. Returns whether the protocol supports it.

ya.image_show(image_url, ui.Rect { x = 0, y = 0, w = 20, h = 10 })

ya.image_precache(url) -> bool

Pre-cache an image for faster subsequent display.

---

Event & IPC

ya.emit(event, args)

Emit a named event that Yazi or other plugins can listen for.

ya.emit("my_plugin:update", { status = "done" })

ya.ps

Pub-Sub system for publishing and subscribing to events.

Method	Description
ya.ps:subscribe(name, callback)	Subscribe to a named channel
ya.ps:publish(name, data)	Publish data to a channel
ya.ps:unsubscribe(name)	Unsubscribe from a channel

ya.ps:subscribe("custom:refresh", function(data)
  ya.err("Refresh triggered:", data)
end)

ya.dds

Data Distribution Service — communicate between Yazi instances.

Method	Description
ya.dds:publish(name, data)	Publish to all Yazi instances
ya.dds:subscribe(name, callback)	Subscribe to cross-instance events

---

Sync & Async

ya.sync(callback)

Execute a callback in the sync context from an async plugin. Cloned values must be passed explicitly.

local file = cx.active.current.hovered
ya.sync(function()
  -- sync context — can access cx
  local name = file.name
  -- ...
end)

ya.hide()

Hide the plugin UI and return to the previous state.

---

Input & Open

ya.input(opts) -> string

Show an input prompt and return the user's input.

Option	Type	Description
title	string	Prompt title
default	string	Default value
position	{ "top", "bottom" }	Position on screen

local name = ya.input {
  title = "Enter name:",
  default = "untitled",
}

ya.open(url)

Open a URL with the system's default application (or Yazi's open rules).

ya.open(Url.from_str("https://example.com"))

---

Manager

ya.manager

Access to the file manager state.

Field/Method	Description
ya.manager:cd(url)	Change the current directory

ya.manager:cd(Url.from_str("~/Documents"))

---

Mount

ya.mount

Filesystem mount information.

Method	Description
ya.mount:list()	List mount points

---

Other

Function	Description
ya.err(msg)	Write to the Yazi error/log output (stderr)
ya.time()	Get current Unix timestamp
ya.toast(type, title, text)	Show a notification toast ("info", "warn", or "error")

ya.toast

ya.toast("info", "Plugin", "Operation completed successfully")
ya.toast("error", "Plugin", "Something went wrong")
ya.toast("warn", "Plugin", "Deprecated API used")

ya.err

ya.err("Debug: hovered file is " .. tostring(file))

info

ya.err output goes to Yazi's log file (visible via ya.logs or the inspect action in the task manager).