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 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.
​
name
string
required
Area name: "current", "preview", or "progress"
​
return
Rect
Rectangle representing the area
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).
​
return
Permit
Permit handle - UI will show again when dropped
local permit = ui.hide()
-- UI is hidden, can run interactive subprocess
-- UI will restore when permit goes out of scope
Cannot call ui.hide() while main thread is blocked or while already hidden.

​
ui.render()

Request a UI re-render. 
ui.render()

​
ui.redraw(component)

Redraw a component.
​
component
table
required
Component table with redraw() method
​
return
table
Renderable elements
local elements = ui.redraw(component)

​
Text Utilities

​
ui.truncate(str, options)

Truncate a string to fit a maximum width.
​
str
string
required
String to truncate
​
options
table
required
Truncation options
​
options.max
number
required
Maximum width in characters
​
options.rtl
bool
Truncate from left (right-to-left) instead of right (default: false)
​
return
string
Truncated string with ellipsis (…) if needed
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.
​
value
string|Line|Span
required
String or UI element
​
return
number
Display width (accounting for wide characters)
local w = ui.width("Hello 世界")
-- 10 (5 ASCII + 2 wide chars * 2)

​
ui.printable(str)

Convert non-printable characters to printable form.
​
str
string
required
String to convert
​
return
string
String with printable characters only
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.
​
value
number
required
Value between 0 and 100
​
symbol
string
Bar symbol (default: ”█“)
ui.Bar(75, "━"):area(area)

​
ui.Border

Border component. 
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. 
ui.Clear:area(area)

​
ui.Constraint

Layout constraint. 
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.
​
ratio
number
Fill ratio between 0.0 and 1.0
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. 
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.
​
text
string|table
Text string or table of Spans
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.
​
items
Line[]
List of Line components
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. 
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.
​
text
table
List of Lines
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. 
local pos = ui.Pos { x = 10, y = 5 }
local pos = ui.Pos.default(area)  -- Center of area

​
ui.Rect

Rectangle area. 
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.
​
text
string
Text content
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. 
local style = ui.Style()
  :fg("blue")
  :bg("black")
  :bold()
Supports the same methods as ui.Span.

​
ui.Table

Table component. 
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.
​
lines
string|Line[]
Text string or list of Lines
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

Build docs developers (and LLMs) love

Get started for freeTalk to us