Layout

Line, 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`	`Self`
`padding`	`Pad`
Return	`self`

`__new(value)`

Make a new rect.

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

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	`Self`

`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	`Self`

`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	`Self`

`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	`Self`

`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	`Self`

`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	`Self`

`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	`Self`

`__new(top, right, bottom, left)`

Make a new padding.

In/Out	Type
`top`	`integer`
`right`	`integer`
`bottom`	`integer`
`left`	`integer`
Return	`Self`

Pos

Pos represents a position, which is composed of an origin and an offset relative to that origin:

ui.Pos { "center", x = 5, y = 3, w = 20, h = 10 }

Its only parameter is a table containing the following keys:

[1]: Origin of the position.
x: X-offset relative to the origin, default is 0.
y: Y-offset relative to the origin, default is 0.
w: Width, default is 0.
h: Height, default is 0.

`[1]`

Origin of the position.


Type	`Origin`

`x`

X-offset relative to the origin.


Type	`integer`

`y`

Y-offset relative to the origin.


Type	`integer`

`w`

Width of the position.


Type	`integer`

`h`

Height of the position.


Type	`integer`

`__new(value)`

Make a new position.

In/Out	Type
`value`	`{ [1]: Origin, x?: integer, y?: integer, w?: integer, h?: integer }`
Return	`Self`

Style

Create a style:

ui.Style()

`fg(self, color)`

Apply a foreground color.

In/Out	Type
`self`	`Self`
`color`	`Color`
Return	`self`

`bg(self, color)`

Apply a background color.

In/Out	Type
`self`	`Self`
`color`	`Color`
Return	`self`

`bold(self)`

Apply a bold style.

In/Out	Type
`self`	`Self`
Return	`self`

`dim(self)`

Apply a dim style.

In/Out	Type
`self`	`Self`
Return	`self`

`italic(self)`

Apply an italic style.

In/Out	Type
`self`	`Self`
Return	`self`

`underline(self)`

Apply an underline style.

In/Out	Type
`self`	`Self`
Return	`self`

`blink(self)`

Apply a blink style.

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

In/Out	Type
`self`	`Self`
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`	`Self`
Return	`self`

`reverse(self)`

Apply a reverse style.

In/Out	Type
`self`	`Self`
Return	`self`

`hidden(self)`

Apply a hidden style.

In/Out	Type
`self`	`Self`
Return	`self`

`crossed(self)`

Apply a crossed style.

In/Out	Type
`self`	`Self`
Return	`self`

`reset(self)`

Apply a reset style.

In/Out	Type
`self`	`Self`
Return	`self`

`patch(self, another)`

Patch the style with another.

In/Out	Type
`self`	`Self`
`another`	`Self`
Return	`self`
Private	This method can't be inherited.

`__new()`

Make a new style.

In/Out	Type
Return	`Self`

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"))


Inherit	`Style`	To call `Style` methods on it directly

`visible(self)`

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

In/Out	Type
`self`	`Self`
Return	`boolean`

`style(self, style)`

Set the style of the span.

In/Out	Type
`self`	`Self`
`style`	`Style`
Return	`self`

Span inherits from Style, besides applying a 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)`

Make a new span.

In/Out	Type
`value`	`AsSpan`
Return	`Self`

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") }


Inherit	`Style`	To call `Style` methods on it directly

`area(self, rect)`

Set the area of the line.

In/Out	Type
`self`	`Self`
`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`	`Self`
Return	`integer`

`align(self, align)`

Set the alignment of the line.

In/Out	Type
`self`	`Self`
`align`	`Align`
Return	`self`

`visible(self)`

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

In/Out	Type
`self`	`Self`
Return	`boolean`

`style(self, style)`

Set the style of the line.

In/Out	Type
`self`	`Self`
`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)`

Make a new line.

In/Out	Type
`value`	`AsLine`
Return	`Self`

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.


Inherit	`Style`	To call `Style` methods on it directly

`area(self, rect)`

Set the area of the text.

In/Out	Type
`self`	`Self`
`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`	`Self`
`align`	`Align`
Return	`self`

`wrap(self, wrap)`

Set the wrap of the text.

In/Out	Type
`self`	`Self`
`wrap`	`Wrap`
Return	`self`

`max_width(self)`

Calculate the maximum width of the text across all lines.

In/Out	Type
`self`	`Self`
Return	`integer`

`style(self, style)`

Set the style of the text.

In/Out	Type
`self`	`Self`
`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)`

Make a new text.

In/Out	Type
`value`	`AsText`
Return	`Self`

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`	`Self`
`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`	`Self`	-
`margin`	`integer`	Positive integer
Return	`self`	-

`margin_h(self, margin)`

Set the horizontal margin of the layout.

In/Out	Type	Note
`self`	`Self`	-
`margin`	`integer`	Positive integer
Return	`self`	-

`margin_v(self, margin)`

Set the vertical margin of the layout.

In/Out	Type	Note
`self`	`Self`	-
`margin`	`integer`	Positive integer
Return	`self`	-

`constraints(self, constraints)`

Set the constraints of the layout.

In/Out	Type
`self`	`Self`
`constraints`	`Constraint[]`
Return	`self`

`split(self, rect)`

Split the layout into multiple Rects according to the constraints.

In/Out	Type
`self`	`Self`
`rect`	`Rect`
Return	`Rect[]`

`__new()`

Make a new layout.

In/Out	Type
Return	`Self`

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:

ui.Constraint.Min(min)
ui.Constraint.Max(max)
ui.Constraint.Length(len)
ui.Constraint.Percentage(p)
ui.Constraint.Ratio(num, den)
ui.Constraint.Fill(scale)

`Min(min)`

Applies a minimum size constraint to the element.

In/Out	Type
`min`	`integer`
Return	`Self`

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	`Self`

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	`Self`

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	`Self`

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	`Self`

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	`Self`

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`	`Self`
`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`	`Self`
`style`	`Style`
Return	`self`

`__new(value)`

Make a new list.

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

Bar

Create a bar:

ui.Bar(edge)

The first attribute denotes the direction of the bar and accepts an Edge constant.

`area(self, rect)`

Set the area of the bar.

In/Out	Type
`self`	`Self`
`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`	`Self`
`symbol`	`string`
Return	`self`

`style(self, style)`

Set the style of the bar.

In/Out	Type
`self`	`Self`
`style`	`Style`
Return	`self`

`__new(edge)`

Make a new bar.

In/Out	Type
`edge`	`Edge`
Return	`Self`

Border

Create a border:

ui.Border(edge)

The first attribute denotes the edge of the border and accepts an Edge constant.

`area(self, rect)`

Set the area of the border.

In/Out	Type
`self`	`Self`
`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`	`Self`
`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`	`Self`
`style`	`Style`
Return	`self`

`__new(edge)`

Make a new border.

In/Out	Type
`edge`	`Edge`
Return	`Self`

Gauge

Create a gauge:

ui.Gauge()

`area(self, rect)`

Set the area of the gauge.

In/Out	Type
`self`	`Self`
`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`	`Self`
`percent`	`integer`
Return	`self`

`ratio(self, ratio)`

Set the ratio of the gauge.

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

`label(self, label)`

Set the label of the gauge.

In/Out	Type
`self`	`Self`
`label`	`string`
Return	`self`

`style(self, style)`

Set the style of everything except the gauge itself.

In/Out	Type
`self`	`Self`
`style`	`Style`
Return	`self`

`gauge_style(self, style)`

Set the style of the gauge itself.

In/Out	Type
`self`	`Self`
`style`	`Style`
Return	`self`

`__new()`

Make a new gauge.

In/Out	Type
Return	`Self`

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`	`Self`
`rect`	`Rect?`
Return	`self` \| `Rect`

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

`__new(rect)`

Make a new clear.

In/Out	Type
`rect`	`Rect`
Return	`Self`

Align

Alignment of an element such as Text or Line.

`LEFT`

Align to the left.


Type	`Self`

`CENTER`

Align to the center.


Type	`Self`

`RIGHT`

Align to the right.


Type	`Self`

Wrap

Wrapping behavior of a Text.

`NO`

Disables wrapping.


Type	`Self`

`YES`

Enables wrapping.


Type	`Self`

`TRIM`

Enables wrapping and trims the leading whitespace.


Type	`Self`

Edge

Which edges of elements such as Bar or Border should be applied.

`NONE`

No edge is applied.


Type	`Self`

`TOP`

Applies the top edge.


Type	`Self`

`RIGHT`

Applies the right edge.


Type	`Self`

`BOTTOM`

Applies the bottom edge.


Type	`Self`

`LEFT`

Applies the left edge.


Type	`Self`

`ALL`

Applies all edges.


Type	`Self`

Rect
Pad
Pos
Style
Span
Line
Text
Layout
Constraint
List
Bar
Border
Gauge
Clear
- area(self, rect)
- __new(rect)
Align
Wrap
Edge

Rect​

x​

y​

w​

h​

left​

right​

top​

bottom​

pad(self, padding)​

__new(value)​

Pad​

top​

right​

bottom​

left​

top(top)​

right(right)​

bottom(bottom)​

left(left)​

x(x)​

y(y)​

xy(x, y)​

__new(top, right, bottom, left)​

Pos​

[1]​

x​

y​

w​

h​

__new(value)​

Style​

fg(self, color)​

bg(self, color)​

bold(self)​

dim(self)​

italic(self)​

underline(self)​

blink(self)​

blink_rapid(self)​

reverse(self)​

hidden(self)​

crossed(self)​

reset(self)​

patch(self, another)​

__new()​

Span​

visible(self)​

style(self, style)​

__new(value)​

Line​

area(self, rect)​

width(self)​

align(self, align)​

visible(self)​

style(self, style)​

__new(value)​

Text​

area(self, rect)​

align(self, align)​

wrap(self, wrap)​

max_width(self)​

style(self, style)​

__new(value)​

Layout​

direction(self, direction)​

margin(self, margin)​

margin_h(self, margin)​

margin_v(self, margin)​

constraints(self, constraints)​

split(self, rect)​

__new()​

Constraint​

Min(min)​

Max(max)​

Length(len)​

Percentage(p)​

Ratio(num, den)​

Fill(scale)​

List​

Rect

`x`

`y`

`w`

`h`

`left`

`right`

`top`

`bottom`

`pad(self, padding)`

`__new(value)`

Pad

`top`

`right`

`bottom`

`left`

`top(top)`

`right(right)`

`bottom(bottom)`

`left(left)`

`x(x)`

`y(y)`

`xy(x, y)`

`__new(top, right, bottom, left)`

Pos

`[1]`

`x`

`y`

`w`

`h`

`__new(value)`

Style

`fg(self, color)`

`bg(self, color)`

`bold(self)`

`dim(self)`

`italic(self)`

`underline(self)`

`blink(self)`

`blink_rapid(self)`

`reverse(self)`

`hidden(self)`

`crossed(self)`

`reset(self)`

`patch(self, another)`

`__new()`

Span

`visible(self)`

`style(self, style)`

`__new(value)`

Line

`area(self, rect)`

`width(self)`

`align(self, align)`

`visible(self)`

`style(self, style)`

`__new(value)`

Text

`area(self, rect)`

`align(self, align)`

`wrap(self, wrap)`

`max_width(self)`

`style(self, style)`

`__new(value)`

Layout

`direction(self, direction)`

`margin(self, margin)`

`margin_h(self, margin)`

`margin_v(self, margin)`

`constraints(self, constraints)`

`split(self, rect)`

`__new()`

Constraint

`Min(min)`

`Max(max)`

`Length(len)`

`Percentage(p)`

`Ratio(num, den)`

`Fill(scale)`

List