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.

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