Yazi Core API

Core Yazi API functions and utilities

The ya namespace provides core Yazi functionality including async operations, logging, UI helpers, and system utilities.

Async Operations

ya.async(fn)

Execute a function asynchronously in the background.

fn · function · required

Async function to execute

return · Handle

Handle to the async task

local handle = ya.async(function()
  local files, err = fs.read_dir(url, { limit = 100 })
  if files then
    -- Process files
  end
end)

Introduced in v25.12.29. See #3422.

ya.sync(fn)

Create a sync block that executes in the main thread with plugin context access.

fn · function · required

Function to execute in sync context

return · function

Callable function that returns results from sync execution

local get_config = ya.sync(function()
  return plugin.config
end)

local config = get_config()

ya.join(fn1, fn2, ...)

Wait for multiple async functions to complete.

... · function · required

Async functions to join

return · ...

Combined results from all functions

local result1, result2 = ya.join(
  function() return fs.cha(url1) end,
  function() return fs.cha(url2) end
)

ya.sleep(ms)

Sleep for specified milliseconds (async).

ms · number · required

Milliseconds to sleep

ya.sleep(1000)  -- Sleep for 1 second

Channels

ya.chan(type, buffer?)

Create a channel for async communication.

type · string · required

Channel type: "mpsc" or "oneshot"

buffer · number

Buffer size for mpsc (omit for unbounded)

return · Sender, Receiver

Channel sender and receiver

-- Unbounded mpsc channel
local tx, rx = ya.chan("mpsc")

-- Bounded mpsc channel
local tx, rx = ya.chan("mpsc", 10)

-- Oneshot channel
local tx, rx = ya.chan("oneshot")

-- Send and receive
tx:send(value)
local value = rx:recv()  -- async

Actions & Events

ya.emit(name, args)

Emit a custom action.

name · string · required

Action name

args · table · required

Action arguments

ya.emit("my-action", { file = url, mode = "fast" })

ya.manager_emit(name, args)

Emit an action to the file manager.

name · string · required

Manager action name (e.g., “open”, “cd”, “select”)

args · table · required

Action arguments

-- Open a file
ya.manager_emit("open", { hovered = true })

-- Change directory
ya.manager_emit("cd", { url })

-- Select files
ya.manager_emit("select", { state = true })

Logging

ya.dbg(...)

Log debug message.

... · any · required

Values to log

ya.dbg("Processing file:", file.url)
ya.dbg("Metadata:", file.cha)

ya.err(...)

Log error message.

... · any · required

Values to log

ya.err("Failed to read file:", err)

Preview Functions

ya.preview_code(options)

Preview a code file with syntax highlighting.

options · table · required

Preview options

options.area · Rect · required

Preview area

options.url · Url · required

File URL

options.skip · number · required

Number of lines to skip

function M:peek(job)
  ya.preview_code {
    area = job.area,
    url = job.file.url,
    skip = job.skip,
  }
end

ya.preview_widget(job, widget)

Set preview widget.

job · table · required

Preview job

widget · table|Renderable · required

Widget or list of renderable elements

ya.preview_widget(job, ui.Text("Hello"):area(job.area))

-- Multiple widgets
ya.preview_widget(job, {
  ui.List(lines):area(job.area),
  ui.Border:area(job.area),
})

Spotlights

ya.spot_table(name, items)

Create a spotlight table.

name · string · required

Spotlight name

items · table · required

Table items

ya.spot_table("metadata", {
  { "Name", file.name },
  { "Size", ya.readable_size(file.cha.len) },
})

ya.spot_widgets(name, widgets)

Create a spotlight with custom widgets.

name · string · required

Spotlight name

widgets · table · required

List of renderable widgets

ya.spot_widgets("custom", {
  ui.Text("Custom view"):area(area),
})

User Interaction

ya.input(options)

Show an input prompt.

options · table · required

Input options

options.title · string · required

Prompt title

options.value · string

Default value

options.pos · table

Cursor position {x, y} or ui.Pos

options.realtime · bool

Emit events in real-time as user types

return · string|nil

User input, or nil if cancelled

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

if input then
  ya.dbg("User entered: " .. input)
end

ya.confirm(options)

Show a confirmation dialog.

options · table · required

Confirmation options

options.title · string · required

Dialog title

options.body · string · required

Dialog body text

options.pos · table

Dialog position

return · bool

True if confirmed, false if cancelled

local confirmed = ya.confirm {
  title = "Delete file?",
  body = "This action cannot be undone.",
}

if confirmed then
  fs.remove("file", url)
end

ya.notify(options)

Show a notification.

options · table · required

Notification options

options.title · string · required

Notification title

options.body · string · required

Notification body

options.level · string

Level: "info", "warn", "error" (default: info)

options.timeout · number

Auto-dismiss timeout in seconds

ya.notify {
  title = "Task Complete",
  body = "File processing finished.",
  level = "info",
  timeout = 5,
}

Caching

ya.file_cache(job)

Access file preview cache.

job · table · required

Preview job

return · string|nil

Cached data, or nil if not cached

function M:preload(job)
  local cache = ya.file_cache(job)
  if cache then
    return 1  -- Already cached
  end
  
  -- Generate cache...
  return 2
end

Utilities

ya.id(type)

Generate a unique ID.

type · string · required

ID type: "app" or "ft" (file ticket)

return · Id

Unique identifier

local app_id = ya.id("app")
local ticket = ya.id("ft")

ya.drop(userdata)

Drop/close a userdata handle (file descriptor, process handle, etc.).

userdata · userdata · required

Handle to drop

local fd = access:open(url)
-- Use fd...
ya.drop(fd)

ya.quote(str)

Shell-quote a string.

str · string · required

String to quote

return · string

Shell-quoted string

local quoted = ya.quote("file with spaces.txt")
-- "'file with spaces.txt'"

ya.clipboard(text?)

Get or set clipboard contents.

text · string

Text to set (omit to get)

return · string|nil

Clipboard text (when getting), or nil

-- Get clipboard
local text = ya.clipboard()

-- Set clipboard
ya.clipboard("Copy this text")

ya.hash(text)

Compute hash of a string.

text · string · required

Text to hash

return · number

Hash value

local hash = ya.hash(tostring(url))

ya.time()

Get current timestamp.

return · number

Unix timestamp in seconds

local now = ya.time()

System Info

ya.user_name(uid?)

Get username from UID.

uid · number

User ID (omit for current user)

return · string|nil

Username, or nil if not found

local user = ya.user_name()
local owner = ya.user_name(file.cha.uid)

ya.group_name(gid?)

Get group name from GID.

gid · number

Group ID (omit for current user)

return · string|nil

Group name, or nil if not found

local group = ya.group_name(file.cha.gid)

ya.uid()

Get current user ID.

return · number

User ID

local uid = ya.uid()

ya.gid()

Get current group ID.

return · number

Group ID

local gid = ya.gid()

ya.host_name()

Get hostname.

return · string|nil

Hostname, or nil

local host = ya.host_name()

ya.target_os()

Get target OS name.

return · string

OS name: "linux", "macos", "windows", etc.

if ya.target_os() == "windows" then
  -- Windows-specific code
end

ya.target_family()

Get target OS family.

return · string

OS family: "unix" or "windows"

if ya.target_family() == "unix" then
  -- Unix-specific code
end

Process Info

ya.proc_info(pid?)

Get process information.

pid · number

Process ID (omit for current process)

return · table|nil

Process info table, or nil

local info = ya.proc_info()
if info then
  ya.dbg("PID: " .. info.pid)
  ya.dbg("Name: " .. info.name)
end

Image Operations

ya.image_info(url)

Get image metadata.

url · Url · required

Image file URL

return · table|nil, Error

Image info, or (nil, error)

local info, err = ya.image_info(url)
if info then
  ya.dbg(string.format("%dx%d", info.width, info.height))
end

ya.image_show(url, rect)

Display an image.

url · Url · required

Image URL

rect · Rect · required

Display area

return · Rect|nil, Error

Actual display area, or (nil, error)

local area, err = ya.image_show(url, rect)

ya.image_precache(src, dist)

Pre-cache an image.

src · Url · required

Source image URL

dist · Url · required

Destination cache path (must be local)

return · bool, Error|nil

Success boolean, or (false, error)

local ok, err = ya.image_precache(src, cache_path)

JSON

ya.json_encode(value)

Encode Lua value as JSON.

value · any · required

Value to encode

return · string

JSON string

local json = ya.json_encode({ name = "test", count = 42 })
-- '{"name":"test","count":42}'

ya.json_decode(json)

Decode JSON string.

json · string · required

JSON string

return · any

Decoded Lua value

local data = ya.json_decode('{"name":"test"}')
ya.dbg(data.name)  -- "test"

Which-Key

ya.which(key?)

Show or hide which-key interface.

key · string

Key to show candidates for (omit to hide)

-- Show which-key for a prefix
ya.which("g")

-- Hide which-key
ya.which()