Skip to main content

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.

The cx global variable provides read-only access to the current application state.

​
Structure

cx = {
  active = { ... },  -- Active tab
  tabs = { ... },    -- All tabs
  tasks = { ... },   -- Task manager state
  yanked = { ... },  -- Yanked files
  which = { ... },   -- Which-key state (if active)
  layer = Layer,     -- Current layer (mgr/help/input/...)
}

​
Active Tab

cx.active provides information about the currently active tab.

​
cx.active.current

Current directory view. 
local current = cx.active.current

-- Current working directory
local cwd = current.cwd  -- Url

-- Hovered file
local hovered = current.hovered  -- File|nil
if hovered then
  ya.dbg("Hovered: " .. tostring(hovered.url))
end

-- All files in current directory
for _, file in ipairs(current.files) do
  ya.dbg(file.url)
end

-- Current window of visible files
for _, file in ipairs(current.window) do
  -- Only files visible in the current view
end

​
Fields

  • cwd (Url) - Current working directory
  • hovered (File|nil) - Currently hovered file
  • files (File[]) - All files in directory
  • window (File[]) - Visible files in current view
  • offset (number) - Scroll offset
  • cursor (number) - Cursor position (0-based)

​
cx.active.preview

Preview pane state. 
local preview = cx.active.preview

-- Preview skip/scroll position
local skip = preview.skip  -- number

-- For folder previews
if preview.folder then
  local folder = preview.folder
  ya.dbg("Preview folder: " .. tostring(folder.cwd))
  ya.dbg("Files: " .. #folder.files)
  
  -- Visible window in folder preview
  for _, file in ipairs(folder.window) do
    ya.dbg(file.url)
  end
end

​
Fields

  • skip (number) - Preview scroll position
  • folder (Folder|nil) - Folder preview state (if previewing a folder)

​
Folder Fields

  • cwd (Url) - Folder URL
  • files (File[]) - Files in folder
  • window (File[]) - Visible files in preview
  • offset (number) - Scroll offset
  • cursor (number) - Cursor position

​
cx.active.selected

Map of selected files. 
-- Iterate selected files
for url, _ in pairs(cx.active.selected) do
  ya.dbg("Selected: " .. tostring(url))
end

-- Count selected files
local count = 0
for _ in pairs(cx.active.selected) do
  count = count + 1
end

​
cx.active.pref

Tab preferences. 
local linemode = cx.active.pref.linemode  -- string

​
cx.active:history(url)

Get history entry for a URL.
​
url
Url
required
Directory URL
​
return
Folder|nil
Cached folder state, or nil
local folder = cx.active:history(url)
if folder then
  ya.dbg("Cached files: " .. #folder.files)
end

​
Tabs

cx.tabs is a list of all tabs with additional properties. 
-- Current tab index (1-based)
local current = cx.tabs.idx

-- Iterate all tabs
for i, tab in ipairs(cx.tabs) do
  ya.dbg(string.format("Tab %d: %s", i, tab.name))
end

-- Access specific tab
local first_tab = cx.tabs[1]

​
Tab Fields

Each tab has the same structure as cx.active:
  • current - Current directory view
  • preview - Preview state
  • selected - Selected files
  • pref - Tab preferences
  • name - Tab name (string)

​
Tasks

cx.tasks provides access to the task manager state.

​
cx.tasks.summary

Task summary information. 
local summary = cx.tasks.summary
ya.dbg(string.format("Tasks: %d running, %d total", summary.running, summary.total))

​
Summary Fields

  • running (number) - Number of running tasks
  • total (number) - Total number of tasks
  • found (number) - Files found
  • processed (number) - Files processed
  • percent (number) - Overall progress (0-100)

​
cx.tasks.snaps

List of task snapshots. 
for i, snap in ipairs(cx.tasks.snaps) do
  ya.dbg(snap.name)  -- Task name
  ya.dbg(snap.percent)  -- Progress percentage
end

​
cx.tasks.cursor

Current task cursor position (0-based). 
local selected_task = cx.tasks.snaps[cx.tasks.cursor + 1]

​
Yanked Files

cx.yanked contains information about copied/cut files. 
-- Check if files are cut (move) or copied
if cx.yanked.is_cut then
  ya.dbg("Files will be moved")
else
  ya.dbg("Files will be copied")
end

-- Iterate yanked files
for url, _ in pairs(cx.yanked) do
  ya.dbg("Yanked: " .. tostring(url))
end

-- Count yanked files
local count = #cx.yanked

​
Yanked Fields

  • is_cut (bool) - True if cut (move), false if copy
  • [url] - Map of yanked file URLs

​
Which-Key

cx.which provides state for the which-key component (when active). 
if cx.which then
  -- Which-key is active
  local layer = cx.which.layer  -- Layer name
  local cands = cx.which.cands  -- Candidate keys
end
See #3617 for details.

​
Layer

cx.layer indicates the current UI layer. 
if tostring(cx.layer) == "mgr" then
  -- In file manager layer
elseif tostring(cx.layer) == "help" then
  -- Help screen is visible
end
Possible values:
  • "mgr" - File manager
  • "help" - Help screen
  • "input" - Input prompt
  • "confirm" - Confirmation dialog
  • "which" - Which-key screen
  • "pick" - Picker dialog

​
Examples

​
Get Selected Files or Hovered

function get_targets()
  local files = {}
  
  -- Check if files are selected
  for url, _ in pairs(cx.active.selected) do
    files[#files + 1] = url
  end
  
  -- If nothing selected, use hovered
  if #files == 0 and cx.active.current.hovered then
    files[1] = cx.active.current.hovered.url
  end
  
  return files
end

​
Check if Preview is a Folder

local folder = cx.active.preview.folder
if folder and folder.cwd == job.file.url then
  -- Preview is showing the expected folder
  for _, file in ipairs(folder.window) do
    -- Process visible files
  end
end

​
Access Other Tab’s State

-- Get first tab's current directory
if #cx.tabs > 0 then
  local first_tab = cx.tabs[1]
  local cwd = first_tab.current.cwd
  ya.dbg("First tab CWD: " .. tostring(cwd))
end

Build docs developers (and LLMs) love

Get started for freeTalk to us