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

# UI API

> UI rendering components and utilities for Yazi plugins

The `ui` namespace provides components and utilities for rendering UI elements in Yazi plugins.

## Layout Utilities

### `ui.area(name)`

Get the screen area for a component.

<ParamField path="name" type="string" required>
  Area name: `"current"`, `"preview"`, or `"progress"`
</ParamField>

<ResponseField name="return" type="Rect">
  Rectangle representing the area
</ResponseField>

```lua theme={null}
local area = ui.area("preview")
ya.dbg(string.format("Preview: %dx%d at (%d,%d)", area.w, area.h, area.x, area.y))
```

### `ui.hide()`

Hide the UI and yield to a subprocess (async).

<ResponseField name="return" type="Permit">
  Permit handle - UI will show again when dropped
</ResponseField>

```lua theme={null}
local permit = ui.hide()
-- UI is hidden, can run interactive subprocess
-- UI will restore when permit goes out of scope
```

<Warning>
  Cannot call `ui.hide()` while main thread is blocked or while already hidden.
</Warning>

### `ui.render()`

Request a UI re-render.

```lua theme={null}
ui.render()
```

### `ui.redraw(component)`

Redraw a component.

<ParamField path="component" type="table" required>
  Component table with `redraw()` method
</ParamField>

<ResponseField name="return" type="table">
  Renderable elements
</ResponseField>

```lua theme={null}
local elements = ui.redraw(component)
```

## Text Utilities

### `ui.truncate(str, options)`

Truncate a string to fit a maximum width.

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

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

<ParamField path="options.max" type="number" required>
  Maximum width in characters
</ParamField>

<ParamField path="options.rtl" type="bool">
  Truncate from left (right-to-left) instead of right (default: false)
</ParamField>

<ResponseField name="return" type="string">
  Truncated string with ellipsis (…) if needed
</ResponseField>

```lua theme={null}
local short = ui.truncate("Long filename.txt", { max = 10 })
-- "Long fil…"

local short_rtl = ui.truncate("Long filename.txt", { max = 10, rtl = true })
-- "…ename.txt"
```

### `ui.width(value)`

Calculate display width of a string or UI element.

<ParamField path="value" type="string|Line|Span" required>
  String or UI element
</ParamField>

<ResponseField name="return" type="number">
  Display width (accounting for wide characters)
</ResponseField>

```lua theme={null}
local w = ui.width("Hello 世界")
-- 10 (5 ASCII + 2 wide chars * 2)
```

### `ui.printable(str)`

Convert non-printable characters to printable form.

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

<ResponseField name="return" type="string">
  String with printable characters only
</ResponseField>

```lua theme={null}
local clean = ui.printable("Hello\x00World")
```

## UI Components

All UI components support chaining methods and must have an area set.

### Common Methods

All components support these methods:

* **`:area(rect)`** - Set component area

### `ui.Bar(value, symbol?)`

Progress bar component.

<ParamField path="value" type="number" required>
  Value between 0 and 100
</ParamField>

<ParamField path="symbol" type="string">
  Bar symbol (default: "█")
</ParamField>

```lua theme={null}
ui.Bar(75, "━"):area(area)
```

### `ui.Border`

Border component.

```lua theme={null}
ui.Border:area(area)
  :style(ui.Style():fg("blue"))
```

#### Methods

* **`:type(type)`** - Border type: `ui.Border.PLAIN`, `ui.Border.ROUNDED`
* **`:style(style)`** - Border style

### `ui.Clear`

Clear a screen area.

```lua theme={null}
ui.Clear:area(area)
```

### `ui.Constraint`

Layout constraint.

```lua theme={null}
ui.Constraint.Percentage(50)
ui.Constraint.Length(10)
ui.Constraint.Min(5)
ui.Constraint.Max(20)
ui.Constraint.Ratio(1, 3)
```

### `ui.Gauge(ratio?)`

Gauge/progress indicator.

<ParamField path="ratio" type="number">
  Fill ratio between 0.0 and 1.0
</ParamField>

```lua theme={null}
ui.Gauge(0.75):area(area):label("75%")
```

#### Methods

* **`:label(text)`** - Set label text
* **`:style(style)`** - Set gauge style

### `ui.Layout`

Layout container for arranging components.

```lua theme={null}
local chunks = ui.Layout()
  :direction(ui.Layout.HORIZONTAL)
  :constraints({ ui.Constraint.Percentage(50), ui.Constraint.Percentage(50) })
  :split(area)
```

#### Methods

* **`:direction(dir)`** - `ui.Layout.HORIZONTAL` or `ui.Layout.VERTICAL`
* **`:constraints(list)`** - List of constraints
* **`:split(area)`** - Split area and return chunks

### `ui.Line(text?)`

Single line of text/spans.

<ParamField path="text" type="string|table">
  Text string or table of Spans
</ParamField>

```lua theme={null}
ui.Line("Hello"):area(area)
ui.Line({ ui.Span("Bold"):bold(), ui.Span(" Normal") }):area(area)
```

#### Methods

* **`:align(align)`** - Set alignment: `ui.Align.LEFT`, `ui.Align.CENTER`, `ui.Align.RIGHT`
* **`:style(style)`** - Set line style

### `ui.List(items?)`

List of lines.

<ParamField path="items" type="Line[]">
  List of Line components
</ParamField>

```lua theme={null}
local lines = {}
for i, file in ipairs(files) do
  lines[i] = ui.Line(file.name)
end

ui.List(lines):area(area)
```

### `ui.Pad`

Padding container.

```lua theme={null}
ui.Pad(1, 2, 1, 2)  -- top, right, bottom, left
```

#### Methods

* **`:position(edge)`** - Edge position: `ui.Edge.TOP`, `ui.Edge.BOTTOM`, etc.

### `ui.Paragraph(text?)`

Multi-line text paragraph.

<ParamField path="text" type="table">
  List of Lines
</ParamField>

```lua theme={null}
ui.Paragraph({ ui.Line("Line 1"), ui.Line("Line 2") })
  :area(area)
  :wrap(ui.Wrap.YES)
```

#### Methods

* **`:wrap(wrap)`** - Wrap mode: `ui.Wrap.NO`, `ui.Wrap.YES`, `ui.Wrap.TRIM`
* **`:align(align)`** - Text alignment

### `ui.Pos`

Screen position.

```lua theme={null}
local pos = ui.Pos { x = 10, y = 5 }
local pos = ui.Pos.default(area)  -- Center of area
```

### `ui.Rect`

Rectangle area.

```lua theme={null}
local rect = ui.Rect { x = 0, y = 0, w = 80, h = 24 }
local rect = ui.Rect {}  -- Default (0, 0, 0, 0)
```

#### Methods

* **`:padding(pad)`** - Apply padding and return inner rect

### `ui.Span(text?)`

Styled text span.

<ParamField path="text" type="string">
  Text content
</ParamField>

```lua theme={null}
ui.Span("Error")
  :fg("red")
  :bold()
  :underline()
```

#### Methods

* **`:fg(color)`** - Foreground color
* **`:bg(color)`** - Background color
* **`:bold()`** - Bold text
* **`:dim()`** - Dim text
* **`:italic()`** - Italic text
* **`:underline()`** - Underline text
* **`:blink()`** - Blinking text
* **`:reverse()`** - Reverse colors
* **`:hidden()`** - Hidden text
* **`:crossed()`** - Strikethrough text
* **`:reset()`** - Reset all styles
* **`:style(style)`** - Apply style object

### `ui.Style`

Style object for components.

```lua theme={null}
local style = ui.Style()
  :fg("blue")
  :bg("black")
  :bold()
```

Supports the same methods as `ui.Span`.

### `ui.Table`

Table component.

```lua theme={null}
local rows = {
  ui.Row { ui.Cell("Name"), ui.Cell("Size") },
  ui.Row { ui.Cell("file.txt"), ui.Cell("1.5K") },
}

ui.Table(rows)
  :area(area)
  :widths({ ui.Constraint.Percentage(70), ui.Constraint.Percentage(30) })
```

#### Methods

* **`:widths(constraints)`** - Column width constraints
* **`:col_spacing(n)`** - Spacing between columns

### `ui.Text(lines?)`

Multi-line styled text.

<ParamField path="lines" type="string|Line[]">
  Text string or list of Lines
</ParamField>

```lua theme={null}
ui.Text("Hello\nWorld")
  :area(area)
  :align(ui.Align.CENTER)
  :wrap(ui.Wrap.YES)
```

#### Methods

* **`:wrap(wrap)`** - Wrap mode
* **`:align(align)`** - Text alignment
* **`:style(style)`** - Text style

## Enums

### `ui.Align`

* `ui.Align.LEFT`
* `ui.Align.CENTER`
* `ui.Align.RIGHT`

### `ui.Wrap`

* `ui.Wrap.NO` - No wrapping
* `ui.Wrap.YES` - Wrap at word boundaries
* `ui.Wrap.TRIM` - Trim whitespace

### `ui.Edge`

* `ui.Edge.TOP`
* `ui.Edge.RIGHT`
* `ui.Edge.BOTTOM`
* `ui.Edge.LEFT`