Context API

Access to Yazi application state and context

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