warning

The content of this document has been updated to align with the upcoming major release of Yazi 0.4.

Please make sure you are using the latest nightly version of Yazi to access these APIs.

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

Properties:

x - x position
y - y position
w - width
h - height
left - left position
right - right position
top - top position
bottom - bottom position

Methods (return self if not specified):

pad(pad) - Apply a Pad

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!

Pad

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

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

Properties:

left - left padding
right - right padding
top - top padding
bottom - bottom padding

If you want to specify only one of them:

ui.Pad.left(left) equal to ui.Pad(left, 0, 0, 0)
ui.Pad.right(right) equal to ui.Pad(0, right, 0, 0)
ui.Pad.top(top) equal to ui.Pad(0, 0, top, 0)
ui.Pad.bottom(bottom) equal to ui.Pad(0, 0, 0, bottom)

Or specify a particular direction for them:

ui.Pad.x(x) equal to ui.Pad(x, x, 0, 0)
ui.Pad.y(y) equal to ui.Pad(0, 0, y, y)
ui.Pad.xy(x, y) equal to ui.Pad(x, x, y, y)

Style

Create a style:

ui.Style()

Methods (return self if not specified):

fg(color) - Set the foreground color of the style, which accepts a Color
bg(color) - Set the background color of the style, which accepts a Color
bold() - Set the style to bold
dim() - Set the style to dim
italic() - Set the style to italic
underline() - Set the style to underline
blink() - Set the style to blink
blink_rapid() - Set the style to blink rapidly
reverse() - Set the style to reverse
hidden() - Set the style to hidden
crossed() - Set the style to crossed
reset() - Reset the style
patch(style) - Patch the style with another 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"))

Methods (return self if not specified):

visible() - Whether the span is visible (includes any printable characters), which returns a boolean.
style(style) - Set the style of the span, which accepts a Style

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

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

Methods (return self if not specified):

area(rect) - accepts a Rect, changing the area of the line. If not specified, returns the current area.
width() - Get the width of the line, which returns an integer.
align(alignment) - Set the alignment of the line. It accepts the following constants:
- ui.Line.LEFT
- ui.Line.CENTER
- ui.Line.RIGHT
visible() - Whether the line is visible (includes any printable characters), which returns a boolean.
style(style) - Set the style of the line, which accepts a Style.

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

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

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.

Methods (return self if not specified):

area(rect) - accepts a Rect, changing the area of the text. If not specified, returns the current area.
align(alignment) - Set the alignment of the text, accepts the following constants:
- ui.Text.LEFT
- ui.Text.CENTER
- ui.Text.RIGHT
wrap(wrap) - Set the wrap of the text, which 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() - Get the maximum width of the text, which returns an integer
style(style) - Set the style of the text, which accepts a Style

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

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

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

Methods (return self if not specified):

direction(direction) - Set the direction of the layout, which accepts the following constants:
- ui.Layout.HORIZONTAL
- ui.Layout.VERTICAL
margin(margin) - Set the margin of the layout, which accepts an positive integer.
margin_h(margin) - Set the horizontal margin of the layout, which accepts an positive integer.
margin_v(margin) - Set the vertical margin of the layout, which accepts an positive integer.
constraints({ constraint, ... }) - Set the constraints of the layout, which accepts a list of Constraint.
split(rect) - Accepts a Rect and split it into multiple Rect according to the constraints.

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

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

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

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

Converts the given percentage to a floating-point value and multiplies that with area. This value is rounded back to a 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

Converts the given ratio to a floating-point value and multiplies that with area. This value is rounded back to a 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

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

Methods (return self if not specified):

area(rect) - accepts a Rect, changing the area of the text. If not specified, returns the current area.
style(style) - Set the style of the list, which accepts a Style

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

Methods (return self if not specified):

area(rect) - accepts a Rect, changing the area of the bar. If not specified, returns the current area.
symbol(symbol) - accepts a string, specifying the symbol for the bar
style(style) - accepts a Style, specifying the style of the 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

Methods (return self if not specified):

area(rect) - accepts a Rect, changing the area of the border. If not specified, returns the current area.
type(type) - accepts a type, specifying the type of the border:
- ui.Border.PLAIN
- ui.Border.ROUNDED
- ui.Border.DOUBLE
- ui.Border.THICK
- ui.Border.QUADRANT_INSIDE
- ui.Border.QUADRANT_OUTSIDE
style(style) - accepts a Style, specifying the style of the border

Gauge

Create a gauge:

ui.Gauge()

Methods (return self if not specified):

area(rect) - accepts a Rect, changing the area of the gauge. If not specified, returns the current area.
percent(percent) - Set the percentage of the gauge
ratio(ratio) - Set the ratio of the gauge
label(label) - Set the label of the gauge
style(style) - Set the style of everything except the bar itself, which accepts a Style
gauge_style(style) - Set the style of the bar, which accepts a Style

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

Methods (return self if not specified):

area(rect) - accepts a Rect, changing the area of the clear. If not specified, returns the current area.

Rect​

Pad​

Style​

Span​

Line​

Text​

Layout​

Constraint​

Min(min)​

Max(max)​

Length(len)​

Percentage(p)​

Ratio(num, den)​

Fill(scale)​

List​

Bar​

Border​

Gauge​

Clear​

Rect

Pad

Style

Span

Line

Text

Layout

Constraint

`Min(min)`

`Max(max)`

`Length(len)`

`Percentage(p)`

`Ratio(num, den)`

`Fill(scale)`

List

Bar

Border

Gauge

Clear