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

# Context API

> Access to Yazi application state and context

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

## Structure

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

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

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

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

```lua theme={null}
local linemode = cx.active.pref.linemode  -- string
```

### `cx.active:history(url)`

Get history entry for a URL.

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

<ResponseField name="return" type="Folder|nil">
  Cached folder state, or nil
</ResponseField>

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

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

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

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

```lua theme={null}
local selected_task = cx.tasks.snaps[cx.tasks.cursor + 1]
```

## Yanked Files

`cx.yanked` contains information about copied/cut files.

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

```lua theme={null}
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](https://github.com/sxyazi/yazi/pull/3617) for details.

## Layer

`cx.layer` indicates the current UI layer.

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

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

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

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