Yazi Core API

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.

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.

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).

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

Set preview widget.

job

table

required

Preview job

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

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

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()

API Reference

Documentation Index

​Async Operations

​ya.async(fn)

​ya.sync(fn)

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

​ya.sleep(ms)

​Channels

​ya.chan(type, buffer?)

​Actions & Events

​ya.emit(name, args)

​ya.manager_emit(name, args)

​Logging

​ya.dbg(...)

​ya.err(...)

​Preview Functions

​ya.preview_code(options)

​ya.preview_widget(job, widget)

​Spotlights

​ya.spot_table(name, items)

​ya.spot_widgets(name, widgets)

​User Interaction

​ya.input(options)

​ya.confirm(options)

​ya.notify(options)

​Caching

​ya.file_cache(job)

​Utilities

​ya.id(type)

​ya.drop(userdata)

​ya.quote(str)

​ya.clipboard(text?)

​ya.hash(text)

​ya.time()

​System Info

​ya.user_name(uid?)

​ya.group_name(gid?)

​ya.uid()

​ya.gid()

​ya.host_name()

​ya.target_os()

​ya.target_family()

​Process Info

​ya.proc_info(pid?)

​Image Operations

​ya.image_info(url)

​ya.image_show(url, rect)

​ya.image_precache(src, dist)

​JSON

​ya.json_encode(value)

​ya.json_decode(json)

​Which-Key

​ya.which(key?)

Build docs developers (and LLMs) love

Async Operations

`ya.async(fn)`

`ya.sync(fn)`

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

`ya.sleep(ms)`

Channels

`ya.chan(type, buffer?)`

Actions & Events

`ya.emit(name, args)`

`ya.manager_emit(name, args)`

Logging

`ya.dbg(...)`

`ya.err(...)`

Preview Functions

`ya.preview_code(options)`

`ya.preview_widget(job, widget)`

Spotlights

`ya.spot_table(name, items)`

`ya.spot_widgets(name, widgets)`

User Interaction

`ya.input(options)`

`ya.confirm(options)`

`ya.notify(options)`

Caching

`ya.file_cache(job)`

Utilities

`ya.id(type)`

`ya.drop(userdata)`

`ya.quote(str)`

`ya.clipboard(text?)`

`ya.hash(text)`

`ya.time()`

System Info

`ya.user_name(uid?)`

`ya.group_name(gid?)`

`ya.uid()`

`ya.gid()`

`ya.host_name()`

`ya.target_os()`

`ya.target_family()`

Process Info

`ya.proc_info(pid?)`

Image Operations

`ya.image_info(url)`

`ya.image_show(url, rect)`

`ya.image_precache(src, dist)`

JSON

`ya.json_encode(value)`

`ya.json_decode(json)`

Which-Key

`ya.which(key?)`