Skip to main content

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.

Typeinteger

y

Y position of the rect.

Typeinteger

w

Width of the rect.

Typeinteger

h

Height of the rect.

Typeinteger

left

Left position of the rect.

Typeinteger

right

Right position of the rect.

Typeinteger

top

Top position of the rect.

Typeinteger

bottom

Bottom position of the rect.

Typeinteger

pad(self, padding)

Apply a padding to the rect.

In/OutType
selfSelf
paddingPad
Returnself

__new(value)

Make a new rect.

In/OutType
value{ x: integer?, y: integer?, w: integer?, h: integer? }
ReturnSelf

Pad

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

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

top

Top padding.

Typeinteger

right

Right padding.

Typeinteger

bottom

Bottom padding.

Typeinteger

left

Left padding.

Typeinteger

top(top)

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

In/OutType
topinteger
ReturnSelf

right(right)

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

In/OutType
rightinteger
ReturnSelf

bottom(bottom)

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

In/OutType
bottominteger
ReturnSelf

left(left)

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

In/OutType
leftinteger
ReturnSelf

x(x)

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

In/OutType
xinteger
ReturnSelf

y(y)

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

In/OutType
yinteger
ReturnSelf

xy(x, y)

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

In/OutType
xinteger
yinteger
ReturnSelf

__new(top, right, bottom, left)

Make a new padding.

In/OutType
topinteger
rightinteger
bottominteger
leftinteger
ReturnSelf

Style

Create a style:

ui.Style()

fg(self, color)

Apply a foreground color.

In/OutType
selfSelf
colorColor
Returnself

bg(self, color)

Apply a background color.

In/OutType
selfSelf
colorColor
Returnself

bold(self)

Apply a bold style.

In/OutType
selfSelf
Returnself

dim(self)

Apply a dim style.

In/OutType
selfSelf
Returnself

italic(self)

Apply an italic style.

In/OutType
selfSelf
Returnself

underline(self)

Apply an underline style.

In/OutType
selfSelf
Returnself

Apply a blink style.

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

In/OutType
selfSelf
Returnself

Apply a rapid blink style.

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

In/OutType
selfSelf
Returnself

reverse(self)

Apply a reverse style.

In/OutType
selfSelf
Returnself

hidden(self)

Apply a hidden style.

In/OutType
selfSelf
Returnself

crossed(self)

Apply a crossed style.

In/OutType
selfSelf
Returnself

reset(self)

Apply a reset style.

In/OutType
selfSelf
Returnself

patch(self, another)

Patch the style with another.

In/OutType
selfSelf
anotherSelf
Returnself
PrivateThis method can't be inherited.

__new()

Make a new style.

In/OutType
ReturnSelf

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"))
InheritStyleTo call Style methods on it directly

visible(self)

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

In/OutType
selfSelf
Returnboolean

style(self, style)

Set the style of the span.

In/OutType
selfSelf
styleStyle
Returnself

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/OutType
valuestring | Self
ReturnSelf

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") }
InheritStyleTo call Style methods on it directly

area(self, rect)

Set the area of the line.

In/OutType
selfSelf
rectRect?
Returnself | Rect

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

width(self)

Calculate the width of the line.

In/OutType
selfSelf
Returninteger

align(self, align)

Set the alignment of the line.

In/OutType
selfSelf
alignAlign
Returnself

visible(self)

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

In/OutType
selfSelf
Returnboolean

style(self, style)

Set the style of the line.

In/OutType
selfSelf
styleStyle
Returnself

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/OutType
valuestring | Span | Self | (string|Span|Self)[]
ReturnSelf

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.

InheritStyleTo call Style methods on it directly

area(self, rect)

Set the area of the text.

In/OutType
selfSelf
rectRect?
Returnself | Rect

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

align(self, align)

Set the alignment of the text.

In/OutType
selfSelf
alignAlign
Returnself

wrap(self, wrap)

Set the wrap of the text.

In/OutType
selfSelf
wrapWrap
Returnself

max_width(self)

Calculate the maximum width of the text across all lines.

In/OutType
selfSelf
Returninteger

style(self, style)

Set the style of the text.

In/OutType
selfSelf
styleStyle
Returnself

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/OutType
valuestring | Span | Line | (string|Span|Line)[]
ReturnSelf

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/OutType
selfSelf
directionDirection
Returnself

The direction accepts the following constants:

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

margin(self, margin)

Set the margin of the layout.

In/OutTypeNote
selfSelf-
marginintegerPositive integer
Returnself-

margin_h(self, margin)

Set the horizontal margin of the layout.

In/OutTypeNote
selfSelf-
marginintegerPositive integer
Returnself-

margin_v(self, margin)

Set the vertical margin of the layout.

In/OutTypeNote
selfSelf-
marginintegerPositive integer
Returnself-

constraints(self, constraints)

Set the constraints of the layout.

In/OutType
selfSelf
constraintsConstraint[]
Returnself

split(self, rect)

Split the layout into multiple Rects according to the constraints.

In/OutType
selfSelf
rectRect
ReturnRect[]

__new()

Make a new layout.

In/OutType
ReturnSelf

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/OutType
mininteger
ReturnSelf

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/OutType
maxinteger
ReturnSelf

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/OutType
leninteger
ReturnSelf

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/OutType
pinteger
ReturnSelf

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/OutType
numinteger
deninteger
ReturnSelf

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/OutType
scaleinteger
ReturnSelf

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/OutType
selfSelf
rectRect?
Returnself | Rect

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

style(self, style)

Set the style of the list.

In/OutType
selfSelf
styleStyle
Returnself

__new(value)

Make a new list.

In/OutType
valuestring | Span | Line | Text | (string|Span|Line|Text)[]
ReturnSelf

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/OutType
selfSelf
rectRect?
Returnself | Rect

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

symbol(self, symbol)

Set the symbol of the bar.

In/OutType
selfSelf
symbolstring
Returnself

style(self, style)

Set the style of the bar.

In/OutType
selfSelf
styleStyle
Returnself

__new(edge)

Make a new bar.

In/OutType
edgeEdge
ReturnSelf

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/OutType
selfSelf
rectRect?
Returnself | Rect

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

type(self, type)

Set the type of the border.

In/OutType
selfSelf
typeinteger
Returnself

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/OutType
selfSelf
styleStyle
Returnself

__new(edge)

Make a new border.

In/OutType
edgeEdge
ReturnSelf

Gauge

Create a gauge:

ui.Gauge()

area(self, rect)

Set the area of the gauge.

In/OutType
selfSelf
rectRect?
Returnself | Rect

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

percent(self, percent)

Set the percentage of the gauge.

In/OutType
selfSelf
percentinteger
Returnself

ratio(self, ratio)

Set the ratio of the gauge.

In/OutTypeNote
selfSelf-
rationumberBetween 0 and 1
Returnself-

label(self, label)

Set the label of the gauge.

In/OutType
selfSelf
labelstring
Returnself

style(self, style)

Set the style of everything except the gauge itself.

In/OutType
selfSelf
styleStyle
Returnself

gauge_style(self, style)

Set the style of the gauge itself.

In/OutType
selfSelf
styleStyle
Returnself

__new()

Make a new gauge.

In/OutType
ReturnSelf

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/OutType
selfSelf
rectRect?
Returnself | Rect

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

__new(rect)

Make a new clear.

In/OutType
rectRect
ReturnSelf

Align

Alignment of an element such as Text or Line.

LEFT

Align to the left.

TypeSelf

CENTER

Align to the center.

TypeSelf

RIGHT

Align to the right.

TypeSelf

Wrap

Wrapping behavior of a Text.

NO

Disables wrapping.

TypeSelf

YES

Enables wrapping.

TypeSelf

TRIM

Enables wrapping and trims the leading whitespace.

TypeSelf

Edge

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

NONE

No edge is applied.

TypeSelf

TOP

Applies the top edge.

TypeSelf

RIGHT

Applies the right edge.

TypeSelf

BOTTOM

Applies the bottom edge.

TypeSelf

LEFT

Applies the left edge.

TypeSelf

ALL

Applies all edges.

TypeSelf