Layout

Text, List, Bar, Border, and Gauge are renderable elements; others need to be placed within any of them.

Rect

A Rect is represented an area within the terminal by four attributes:

ui.Rect {
	x = 10, -- x position
	y = 10, -- y position
	w = 20, -- width
	h = 30, -- height
}

ui.Rect.default  -- Equal to `ui.Rect { x = 0, y = 0, w = 0, h = 0 }`

You can get a pre-computed Rect through ui.Layout(). Note that if you intend to create a Rect yourself, ensure these values are calculated accurately; otherwise, it may cause Yazi to crash!

x

X position of the rect.

Type	integer

y

Y position of the rect.

Type	integer

w

Width of the rect.

Type	integer

h

Height of the rect.

Type	integer

left

Left position of the rect.

Type	integer

right

Right position of the rect.

Type	integer

top

Top position of the rect.

Type	integer

bottom

Bottom position of the rect.

Type	integer

pad(self, padding)

Apply a padding to the rect.

In/Out	Type
self	Rect
padding	Pad
Return	self

__new(value)

In/Out	Type
value	{ x: integer?, y: integer?, w: integer?, h: integer? }
Return	Rect

Pad

Pad represents a padding, and all of its parameters are integers:

ui.Pad(top, right, bottom, left)

top

Top padding.

Type	integer

right

Right padding.

Type	integer

bottom

Bottom padding.

Type	integer

left

Left padding.

Type	integer

top(top)

Create a padding with only top value, which is equal to ui.Pad(top, 0, 0, 0).

In/Out	Type
top	integer
Return	Pad

right(right)

Create a padding with only right value, which is equal to ui.Pad(0, right, 0, 0).

In/Out	Type
right	integer
Return	Pad

bottom(bottom)

Create a padding with only bottom value, which is equal to ui.Pad(0, 0, bottom, 0).

In/Out	Type
bottom	integer

| Return | Pad |

left(left)

Create a padding with only left value, which is equal to ui.Pad(0, 0, 0, left).

In/Out	Type
left	integer
Return	Pad

x(x)

Create a padding on both x-axis, which is equal to ui.Pad(0, x, 0, x).

In/Out	Type
x	integer
Return	Pad

y(y)

Create a padding on both y-axis, which is equal to ui.Pad(y, 0, y, 0).

In/Out	Type
y	integer
Return	Pad

xy(x, y)

Create a padding on both x and y-axis, which is equal to ui.Pad(y, x, y, x).

In/Out	Type
x	integer
y	integer
Return	Pad

__new(top, right, bottom, left)

In/Out	Type
top	integer
right	integer
bottom	integer
left	integer
Return	Pad

Style

Create a style:

ui.Style()

fg(self, color)

Apply a foreground color.

In/Out	Type
self	Style
color	Color
Return	self

bg(self, color)

Apply a background color.

In/Out	Type
self	Style
color	Color
Return	self

bold(self)

Apply a bold style.

In/Out	Type
self	Style
Return	self

dim(self)

Apply a dim style.

In/Out	Type
self	Style
Return	self

italic(self)

Apply an italic style.

In/Out	Type
self	Style
Return	self

underline(self)

Apply an underline style.

In/Out	Type
self	Style
Return	self

blink(self)

Apply a blink style.

Note that this style may not be supported by all terminals.

In/Out	Type
self	Style
Return	self

blink_rapid(self)

Apply a rapid blink style.

Note that this style may not be supported by all terminals.

In/Out	Type
self	Style
Return	self

reverse(self)

Apply a reverse style.

In/Out	Type
self	Style
Return	self

hidden(self)

Apply a hidden style.

In/Out	Type
self	Style
Return	self

crossed(self)

Apply a crossed style.

In/Out	Type
self	Style
Return	self

reset(self)

Apply a reset style.

In/Out	Type
self	Style
Return	self

patch(self, another)

Patch the style with another.

In/Out	Type
self	Style
another	Style
Return	self

__new()

In/Out	Type
Return	Style

Span

ui.Span is the smallest unit of text, yet a component of ui.Line. Create a span:

ui.Span("foo")

For convenience, ui.Span can also accept itself as a argument:

ui.Span(ui.Span("bar"))

visible(self)

Whether the span is visible, i.e. includes any printable characters.

In/Out	Type
self	Span
Return	boolean

style(self, style)

Set the style of the span.

In/Out	Type
self	Span
style	Style
Return	self

Besides applying the whole Style, you can also call those methods of Style directly on it, which means:

local style = ui.Style():fg("white"):bg("black"):bold()
ui.Span("Hello world"):style(style)

can be also written as:

ui.Span("Hello world"):fg("white"):bg("black"):bold()

__new(value)

In/Out	Type
value	string | Span
Return	Span

Line

ui.Line represents a line, consisting of multiple ui.Spans, and it accepts a table of them:

ui.Line { ui.Span("foo"), ui.Span("bar") }

For convenience, the following types are also supported:

-- string
ui.Line("foo")

-- ui.Span
ui.Line(ui.Span("bar"))

-- ui.Line itself
ui.Line(ui.Line("baz"))

-- Mixed table of string, ui.Span, ui.Line
ui.Line { "foo", ui.Span("bar"), ui.Line("baz") }

area(self, rect)

Set the area of the line.

In/Out	Type
self	Line
rect	Rect?
Return	self | Rect

If rect is not specified, it returns the current area.

width(self)

Calculate the width of the line.

In/Out	Type
self	Line
Return	integer

align(self, align)

Set the alignment of the line.

In/Out	Type
self	Line
align	Align
Return	self

The align accepts the following constants:

• ui.Line.LEFT
• ui.Line.CENTER
• ui.Line.RIGHT

visible(self)

Whether the line is visible, i.e. includes any printable characters.

In/Out	Type
self	Line
Return	boolean

style(self, style)

Set the style of the line.

In/Out	Type
self	Line
style	Style
Return	self

Like with Span, you can also call the Style methods on it directly:

ui.Line("Hello world"):fg("white"):bg("black"):bold()

__new(value)

In/Out	Type
value	string | Span | Line | (string|Span|Line)[]
Return	Line

Text

ui.Text is used to represent multi-line text, it takes a table of ui.Line:

ui.Text { ui.Line("foo"), ui.Line("bar") }

For convenience, the following types are also supported:

-- string
ui.Text("foo\nbar")

-- ui.Line
ui.Text(ui.Line("foo"))

-- ui.Span
ui.Text(ui.Span("bar"))

-- Mixed table of string, ui.Line, ui.Span
ui.Text { "foo", ui.Line("bar"), ui.Span("baz") }

You can also use ui.Text.parse(code) to parse an ANSI escape sequence string into a text.

area(self, rect)

Set the area of the text.

In/Out	Type
self	Text
rect	Rect?
Return	self | Rect

If rect is not specified, it returns the current area.

align(self, align)

Set the alignment of the text.

In/Out	Type
self	Text
align	Align
Return	self

The align accepts the following constants:

• ui.Text.LEFT
• ui.Text.CENTER
• ui.Text.RIGHT

wrap(self, wrap)

Set the wrap of the text.

In/Out	Type
self	Text
wrap	Wrap
Return	self

The wrap accepts the following constants:

• ui.Text.WRAP_NO - No wrap
• ui.Text.WRAP - Wrap at the end of the line
• ui.Text.WRAP_TRIM - Wrap at the end of the line, and trim the leading whitespace

max_width(self)

Calculate the maximum width of the text across all lines.

In/Out	Type
self	Text
Return	integer

style(self, style)

Set the style of the text.

In/Out	Type
self	Text
style	Style
Return	self

Like with Span, you can also call the Style methods on it directly:

ui.Text("Hello world"):fg("white"):bg("black"):bold()

__new(value)

In/Out	Type
value	string | Span | Line | (string|Span|Line)[]
Return	Text

Layout

Create a layout:

local areas = ui.Layout()
	:direction(ui.Layout.HORIZONTAL)
	:constraints({ ui.Constraint.Percentage(50), ui.Constraint.Percentage(50) })
	:split(area)

local left = areas[1] -- The first rect
local right = areas[2] -- The second rect

direction(self, direction)

Set the direction of the layout.

In/Out	Type
self	Layout
direction	Direction
Return	self

The direction accepts the following constants:

• ui.Layout.HORIZONTAL
• ui.Layout.VERTICAL

margin(self, margin)

Set the margin of the layout.

In/Out	Type	Note
self	Layout	-
margin	integer	Positive integer
Return	self	-

margin_h(self, margin)

Set the horizontal margin of the layout.

In/Out	Type	Note
self	Layout	-
margin	integer	Positive integer
Return	self	-

margin_v(self, margin)

Set the vertical margin of the layout.

In/Out	Type	Note
self	Layout	-
margin	integer	Positive integer
Return	self	-

constraints(self, constraints)

Set the constraints of the layout.

In/Out	Type
self	Layout
constraints	table<Constraint>
Return	self

split(self, rect)

Split the layout into multiple Rects according to the constraints.

In/Out	Type
self	Layout
rect	Rect
Return	table<Rect>

__new()

In/Out	Type
Return	Layout

Constraint

A constraint that defines the size of a layout element.

Constraints can be used to specify a fixed size, a percentage of the available space, a ratio of the available space, a minimum or maximum size or a fill proportional value for a layout element.

Relative constraints (percentage, ratio) are calculated relative to the entire space being divided, rather than the space available after applying more fixed constraints (min, max, length).

Constraints are prioritized in the following order:

1. ui.Constraint.Min(min)
2. ui.Constraint.Max(max)
3. ui.Constraint.Length(len)
4. ui.Constraint.Percentage(p)
5. ui.Constraint.Ratio(num, den)
6. ui.Constraint.Fill(scale)

Min(min)

Applies a minimum size constraint to the element.

In/Out	Type
min	integer
Return	Constraint

The element size is set to at least the specified amount.

-- { Percentage(100), Min(20) }
-- ┌────────────────────────────┐┌──────────────────┐
-- │            30 px           ││       20 px      │
-- └────────────────────────────┘└──────────────────┘

-- { Percentage(100), Min(10) }
-- ┌──────────────────────────────────────┐┌────────┐
-- │                 40 px                ││  10 px │
-- └──────────────────────────────────────┘└────────┘

Max(max)

Applies a maximum size constraint to the element.

In/Out	Type
max	integer
Return	Constraint

The element size is set to at most the specified amount.

-- { Percentage(0), Max(20) }
-- ┌────────────────────────────┐┌──────────────────┐
-- │            30 px           ││       20 px      │
-- └────────────────────────────┘└──────────────────┘

-- { Percentage(0), Max(10) }
-- ┌──────────────────────────────────────┐┌────────┐
-- │                 40 px                ││  10 px │
-- └──────────────────────────────────────┘└────────┘

Length(len)

Applies a length constraint to the element.

In/Out	Type
len	integer
Return	Constraint

The element size is set to the specified amount:

-- { Length(20), Length(20) }
-- ┌──────────────────┐┌──────────────────┐
-- │       20 px      ││       20 px      │
-- └──────────────────┘└──────────────────┘

-- { Length(20), Length(30) }
-- ┌──────────────────┐┌────────────────────────────┐
-- │       20 px      ││            30 px           │
-- └──────────────────┘└────────────────────────────┘

Percentage(p)

Applies a percentage of the available space to the element.

In/Out	Type
p	integer
Return	Constraint

Converts the given percentage to a floating-point value and multiplies that with area. This value is rounded back to an integer as part of the layout split calculation.

-- { Percentage(75), Fill(1) }
-- ┌────────────────────────────────────┐┌──────────┐
-- │                38 px               ││   12 px  │
-- └────────────────────────────────────┘└──────────┘

-- { Percentage(50), Fill(1) }
-- ┌───────────────────────┐┌───────────────────────┐
-- │         25 px         ││         25 px         │
-- └───────────────────────┘└───────────────────────┘

Ratio(num, den)

Applies a ratio of the available space to the element.

In/Out	Type
num	integer
den	integer
Return	Constraint

Converts the given ratio to a floating-point value and multiplies that with area. This value is rounded back to an integer as part of the layout split calculation.

-- { Ratio(1, 2), Ratio(1, 2) }
-- ┌───────────────────────┐┌───────────────────────┐
-- │         25 px         ││         25 px         │
-- └───────────────────────┘└───────────────────────┘

-- { Ratio(1, 4), Ratio(1, 4), Ratio(1, 4), Ratio(1, 4) }
-- ┌───────────┐┌──────────┐┌───────────┐┌──────────┐
-- │   13 px   ││   12 px  ││   13 px   ││   12 px  │
-- └───────────┘└──────────┘└───────────┘└──────────┘

Fill(scale)

Applies the scaling factor proportional to all other Fill elements to fill excess space.

In/Out	Type
scale	integer
Return	Constraint

The element will only expand or fill into excess available space, proportionally matching other Fill elements while satisfying all other constraints.

-- { Fill(1), Fill(2), Fill(3) }
-- ┌──────┐┌───────────────┐┌───────────────────────┐
-- │ 8 px ││     17 px     ││         25 px         │
-- └──────┘└───────────────┘└───────────────────────┘

-- { Fill(1), Percentage(50), Fill(1) }
-- ┌───────────┐┌───────────────────────┐┌──────────┐
-- │   13 px   ││         25 px         ││   12 px  │
-- └───────────┘└───────────────────────┘└──────────┘

See https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html for more information.

List

Create a List that takes a table of ui.Text:

ui.List { ui.Text("foo"), ui.Text("bar") }

For convenience, the following types are also supported:

-- Table of string
ui.List { "foo", "bar" }

-- Table of ui.Line
ui.List { ui.Line("foo"), ui.Line("bar") }

-- Table of ui.Span
ui.List { ui.Span("foo"), ui.Span("bar") }

-- Mixed table of string, ui.Line, ui.Span
ui.List { "foo", ui.Line("bar"), ui.Span("baz") }

area(self, rect)

Set the area of the list.

In/Out	Type
self	List
rect	Rect?
Return	self | Rect

If rect is not specified, it returns the current area.

style(self, style)

Set the style of the list.

In/Out	Type
self	List
style	Style
Return	self

__new(value)

In/Out	Type
value	string | Span | Line | Text | (string|Span|Line|Text)[]
Return	List

Bar

Create a bar:

ui.Bar(direction)

The first attribute denotes the direction of the bar and accepts the following constants:

• ui.Bar.NONE
• ui.Bar.TOP
• ui.Bar.RIGHT
• ui.Bar.BOTTOM
• ui.Bar.LEFT
• ui.Bar.ALL

area(self, rect)

Set the area of the bar.

In/Out	Type
self	Bar
rect	Rect?
Return	self | Rect

If rect is not specified, it returns the current area.

symbol(self, symbol)

Set the symbol of the bar.

In/Out	Type
self	string
Return	self

style(self, style)

Set the style of the bar.

In/Out	Type
self	Bar
style	Style
Return	self

__new(value)

In/Out	Type
value	Direction
Return	Bar

Border

Create a border:

ui.Border(position)

The first attribute denotes the position of the border and accepts the following constants:

• ui.Border.NONE
• ui.Border.TOP
• ui.Border.RIGHT
• ui.Border.BOTTOM
• ui.Border.LEFT
• ui.Border.ALL

area(self, rect)

Set the area of the border.

In/Out	Type
self	Border
rect	Rect?
Return	self | Rect

If rect is not specified, it returns the current area.

type(self, type)

Set the type of the border.

In/Out	Type
self	Border
type	integer
Return	self

The type accepts the following constants:

• ui.Border.PLAIN
• ui.Border.ROUNDED
• ui.Border.DOUBLE
• ui.Border.THICK
• ui.Border.QUADRANT_INSIDE
• ui.Border.QUADRANT_OUTSIDE

style(self, style)

Set the style of the border.

In/Out	Type
self	Border
style	Style
Return	self

__new(value)

In/Out	Type
value	Position
Return	Border

Gauge

Create a gauge:

ui.Gauge()

area(self, rect)

Set the area of the gauge.

In/Out	Type
self	Gauge
rect	Rect?
Return	self | Rect

If rect is not specified, it returns the current area.

percent(self, percent)

Set the percentage of the gauge.

In/Out	Type
self	Gauge
percent	integer
Return	self

ratio(self, ratio)

Set the ratio of the gauge.

In/Out	Type	Note
self	Gauge	-
ratio	number	Between 0 and 1
Return	self	-

label(self, label)

Set the label of the gauge.

In/Out	Type
self	Gauge
label	string
Return	self

style(self, style)

Set the style of everything except the gauge itself.

In/Out	Type
self	Gauge
style	Style
Return	self

gauge_style(self, style)

Set the style of the gauge itself.

In/Out	Type
self	Gauge
style	Style
Return	self

__new()

In/Out	Type
Return	Gauge

Clear

Clear the content of a specific area, which is a Rect. Place it followed by the component that you want to clear:

local components = {
	ui.Text("..."):area(rect),
	-- ...

	ui.Clear(rect),
}

area(self, rect)

Set the area of the clear.

In/Out	Type
self	Clear
rect	Rect?
Return	self | Rect

If rect is not specified, it returns the current area.

__new()

In/Out	Type
rect	Rect
Return	Clear