Plugin API Reference

ya.* Utility API

Function	Signature	Description
ya.file_cache	ya.file_cache(File) -> string?	Get cache path for a file (creates if missing)
ya.emit	ya.emit(string, table?)	Emit a Yazi event with optional data
ya.image_show	ya.image_show(string, Rect)	Display an image at the given area
ya.image_precache	ya.image_precache(string)	Pre-cache an image in the background
ya.image_clear	ya.image_clear()	Clear displayed images
ya.manager	ya.manager() -> Manager	Get the current manager state
ya.sync	ya.sync(function)	Run a function synchronously on the main thread
ya.hide	ya.hide()	Hide the preview / restore normal view
ya.input	ya.input(string, table?) -> string?	Show an input prompt
ya.open	ya.open(Url)	Open a URL with the system handler
ya.ps	ya.ps() -> Process[]	List running plugin processes
ya.dds	ya.dds() -> DDS	Get the DDS (pub-sub) interface
ya.mount	ya.mount() -> Mount[]	List mounted filesystems
ya.preview_code	ya.preview_code(string, string)	Preview a code file with syntax highlighting
ya.which	ya.which(string, table)	Show a which key binding overlay
ya.notify	ya.notify(string, table)	Show a desktop notification

ya.emit Event Examples

-- Emit a "cd" event to navigate
ya.emit("cd", { url = "/home/user/projects" })

-- Emit a "quit" event
ya.emit("quit")

-- Emit a custom event for plugins
ya.emit("custom-event", { data = "hello" })

Context API

The cx variable (available in plugin callbacks) provides the current state:

Field	Type	Description
cx.active	Pane	The currently focused pane
cx.tabs	Tab[]	All open tabs
cx.tasks	Task[]	Current running tasks
cx.yanked	File[]	Currently yanked files
cx.mode	"normal" / "visual"	Current input mode
cx.panes	Pane[]	All panes (parent, current, preview)
cx.time	number	Current timestamp (monotonic)

Pane Fields

Field	Type	Description
pane.current	File	Currently highlighted file
pane.files	File[]	Files in the current directory
pane.cwd	Url	Current working directory
pane.selected	File[]	Selected files

File Fields

Field	Type	Description
file.url	Url	Full URL of the file
file.name	string	File name
file.ext	string	File extension (lowercase)
file.size	number	File size in bytes
file.cha	Cha	File metadata (permissions, type)
file.is_dir	boolean	Whether the file is a directory

Preload / Peek API

Previewer plugins implement one or both of these methods:

Method	Signature	When Called
:preload(job)	preload(job)	In background to pre-generate cache
:peek(job)	peek(job)	To display the preview

Job Fields

Field	Type	Description
job.file	File	File to preview
job.area	Rect	Available display area (x, y, w, h)
job.skip	number	Number of lines to skip (for text preview)

Plugin Lifecycle Hooks

Hook	Description
:setup()	Called once when plugin is loaded
:preload(job)	Background cache generation
:peek(job)	Foreground preview display
:seek(job)	Handle scroll/seeking within preview