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

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

<ParamField path="fn" type="function" required>
  Async function to execute
</ParamField>

<ResponseField name="return" type="Handle">
  Handle to the async task
</ResponseField>

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

<Note>
  Introduced in v25.12.29. See [#3422](https://github.com/sxyazi/yazi/pull/3422).
</Note>

### `ya.sync(fn)`

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

<ParamField path="fn" type="function" required>
  Function to execute in sync context
</ParamField>

<ResponseField name="return" type="function">
  Callable function that returns results from sync execution
</ResponseField>

```lua theme={null}
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.

<ParamField path="..." type="function" required>
  Async functions to join
</ParamField>

<ResponseField name="return" type="...">
  Combined results from all functions
</ResponseField>

```lua theme={null}
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).

<ParamField path="ms" type="number" required>
  Milliseconds to sleep
</ParamField>

```lua theme={null}
ya.sleep(1000)  -- Sleep for 1 second
```

## Channels

### `ya.chan(type, buffer?)`

Create a channel for async communication.

<ParamField path="type" type="string" required>
  Channel type: `"mpsc"` or `"oneshot"`
</ParamField>

<ParamField path="buffer" type="number">
  Buffer size for mpsc (omit for unbounded)
</ParamField>

<ResponseField name="return" type="Sender, Receiver">
  Channel sender and receiver
</ResponseField>

```lua theme={null}
-- 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.

<ParamField path="name" type="string" required>
  Action name
</ParamField>

<ParamField path="args" type="table" required>
  Action arguments
</ParamField>

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

### `ya.manager_emit(name, args)`

Emit an action to the file manager.

<ParamField path="name" type="string" required>
  Manager action name (e.g., "open", "cd", "select")
</ParamField>

<ParamField path="args" type="table" required>
  Action arguments
</ParamField>

```lua theme={null}
-- 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.

<ParamField path="..." type="any" required>
  Values to log
</ParamField>

```lua theme={null}
ya.dbg("Processing file:", file.url)
ya.dbg("Metadata:", file.cha)
```

### `ya.err(...)`

Log error message.

<ParamField path="..." type="any" required>
  Values to log
</ParamField>

```lua theme={null}
ya.err("Failed to read file:", err)
```

## Preview Functions

### `ya.preview_code(options)`

Preview a code file with syntax highlighting.

<ParamField path="options" type="table" required>
  Preview options
</ParamField>

<ParamField path="options.area" type="Rect" required>
  Preview area
</ParamField>

<ParamField path="options.url" type="Url" required>
  File URL
</ParamField>

<ParamField path="options.skip" type="number" required>
  Number of lines to skip
</ParamField>

```lua theme={null}
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.

<ParamField path="job" type="table" required>
  Preview job
</ParamField>

<ParamField path="widget" type="table|Renderable" required>
  Widget or list of renderable elements
</ParamField>

```lua theme={null}
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.

<ParamField path="name" type="string" required>
  Spotlight name
</ParamField>

<ParamField path="items" type="table" required>
  Table items
</ParamField>

```lua theme={null}
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.

<ParamField path="name" type="string" required>
  Spotlight name
</ParamField>

<ParamField path="widgets" type="table" required>
  List of renderable widgets
</ParamField>

```lua theme={null}
ya.spot_widgets("custom", {
  ui.Text("Custom view"):area(area),
})
```

## User Interaction

### `ya.input(options)`

Show an input prompt.

<ParamField path="options" type="table" required>
  Input options
</ParamField>

<ParamField path="options.title" type="string" required>
  Prompt title
</ParamField>

<ParamField path="options.value" type="string">
  Default value
</ParamField>

<ParamField path="options.pos" type="table">
  Cursor position `{x, y}` or `ui.Pos`
</ParamField>

<ParamField path="options.realtime" type="bool">
  Emit events in real-time as user types
</ParamField>

<ResponseField name="return" type="string|nil">
  User input, or nil if cancelled
</ResponseField>

```lua theme={null}
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.

<ParamField path="options" type="table" required>
  Confirmation options
</ParamField>

<ParamField path="options.title" type="string" required>
  Dialog title
</ParamField>

<ParamField path="options.body" type="string" required>
  Dialog body text
</ParamField>

<ParamField path="options.pos" type="table">
  Dialog position
</ParamField>

<ResponseField name="return" type="bool">
  True if confirmed, false if cancelled
</ResponseField>

```lua theme={null}
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.

<ParamField path="options" type="table" required>
  Notification options
</ParamField>

<ParamField path="options.title" type="string" required>
  Notification title
</ParamField>

<ParamField path="options.body" type="string" required>
  Notification body
</ParamField>

<ParamField path="options.level" type="string">
  Level: `"info"`, `"warn"`, `"error"` (default: info)
</ParamField>

<ParamField path="options.timeout" type="number">
  Auto-dismiss timeout in seconds
</ParamField>

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

## Caching

### `ya.file_cache(job)`

Access file preview cache.

<ParamField path="job" type="table" required>
  Preview job
</ParamField>

<ResponseField name="return" type="string|nil">
  Cached data, or nil if not cached
</ResponseField>

```lua theme={null}
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.

<ParamField path="type" type="string" required>
  ID type: `"app"` or `"ft"` (file ticket)
</ParamField>

<ResponseField name="return" type="Id">
  Unique identifier
</ResponseField>

```lua theme={null}
local app_id = ya.id("app")
local ticket = ya.id("ft")
```

### `ya.drop(userdata)`

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

<ParamField path="userdata" type="userdata" required>
  Handle to drop
</ParamField>

```lua theme={null}
local fd = access:open(url)
-- Use fd...
ya.drop(fd)
```

### `ya.quote(str)`

Shell-quote a string.

<ParamField path="str" type="string" required>
  String to quote
</ParamField>

<ResponseField name="return" type="string">
  Shell-quoted string
</ResponseField>

```lua theme={null}
local quoted = ya.quote("file with spaces.txt")
-- "'file with spaces.txt'"
```

### `ya.clipboard(text?)`

Get or set clipboard contents.

<ParamField path="text" type="string">
  Text to set (omit to get)
</ParamField>

<ResponseField name="return" type="string|nil">
  Clipboard text (when getting), or nil
</ResponseField>

```lua theme={null}
-- Get clipboard
local text = ya.clipboard()

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

### `ya.hash(text)`

Compute hash of a string.

<ParamField path="text" type="string" required>
  Text to hash
</ParamField>

<ResponseField name="return" type="number">
  Hash value
</ResponseField>

```lua theme={null}
local hash = ya.hash(tostring(url))
```

### `ya.time()`

Get current timestamp.

<ResponseField name="return" type="number">
  Unix timestamp in seconds
</ResponseField>

```lua theme={null}
local now = ya.time()
```

## System Info

### `ya.user_name(uid?)`

Get username from UID.

<ParamField path="uid" type="number">
  User ID (omit for current user)
</ParamField>

<ResponseField name="return" type="string|nil">
  Username, or nil if not found
</ResponseField>

```lua theme={null}
local user = ya.user_name()
local owner = ya.user_name(file.cha.uid)
```

### `ya.group_name(gid?)`

Get group name from GID.

<ParamField path="gid" type="number">
  Group ID (omit for current user)
</ParamField>

<ResponseField name="return" type="string|nil">
  Group name, or nil if not found
</ResponseField>

```lua theme={null}
local group = ya.group_name(file.cha.gid)
```

### `ya.uid()`

Get current user ID.

<ResponseField name="return" type="number">
  User ID
</ResponseField>

```lua theme={null}
local uid = ya.uid()
```

### `ya.gid()`

Get current group ID.

<ResponseField name="return" type="number">
  Group ID
</ResponseField>

```lua theme={null}
local gid = ya.gid()
```

### `ya.host_name()`

Get hostname.

<ResponseField name="return" type="string|nil">
  Hostname, or nil
</ResponseField>

```lua theme={null}
local host = ya.host_name()
```

### `ya.target_os()`

Get target OS name.

<ResponseField name="return" type="string">
  OS name: `"linux"`, `"macos"`, `"windows"`, etc.
</ResponseField>

```lua theme={null}
if ya.target_os() == "windows" then
  -- Windows-specific code
end
```

### `ya.target_family()`

Get target OS family.

<ResponseField name="return" type="string">
  OS family: `"unix"` or `"windows"`
</ResponseField>

```lua theme={null}
if ya.target_family() == "unix" then
  -- Unix-specific code
end
```

## Process Info

### `ya.proc_info(pid?)`

Get process information.

<ParamField path="pid" type="number">
  Process ID (omit for current process)
</ParamField>

<ResponseField name="return" type="table|nil">
  Process info table, or nil
</ResponseField>

```lua theme={null}
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.

<ParamField path="url" type="Url" required>
  Image file URL
</ParamField>

<ResponseField name="return" type="table|nil, Error">
  Image info, or (nil, error)
</ResponseField>

```lua theme={null}
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.

<ParamField path="url" type="Url" required>
  Image URL
</ParamField>

<ParamField path="rect" type="Rect" required>
  Display area
</ParamField>

<ResponseField name="return" type="Rect|nil, Error">
  Actual display area, or (nil, error)
</ResponseField>

```lua theme={null}
local area, err = ya.image_show(url, rect)
```

### `ya.image_precache(src, dist)`

Pre-cache an image.

<ParamField path="src" type="Url" required>
  Source image URL
</ParamField>

<ParamField path="dist" type="Url" required>
  Destination cache path (must be local)
</ParamField>

<ResponseField name="return" type="bool, Error|nil">
  Success boolean, or (false, error)
</ResponseField>

```lua theme={null}
local ok, err = ya.image_precache(src, cache_path)
```

## JSON

### `ya.json_encode(value)`

Encode Lua value as JSON.

<ParamField path="value" type="any" required>
  Value to encode
</ParamField>

<ResponseField name="return" type="string">
  JSON string
</ResponseField>

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

### `ya.json_decode(json)`

Decode JSON string.

<ParamField path="json" type="string" required>
  JSON string
</ParamField>

<ResponseField name="return" type="any">
  Decoded Lua value
</ResponseField>

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

## Which-Key

### `ya.which(key?)`

Show or hide which-key interface.

<ParamField path="key" type="string">
  Key to show candidates for (omit to hide)
</ParamField>

```lua theme={null}
-- Show which-key for a prefix
ya.which("g")

-- Hide which-key
ya.which()
```