Nodes

cy currently supports the following layout node types:

Pane: A pane node can be attached to panes that exist in the node tree.
Margins: A margins mode constrains the size of its child node by adding transparent margins.
Split: A split node divides the screen space of its parent node in two and provides it to two other nodes, drawing a line on the screen between them.
Borders: A node is enclosed in borders with an optional title on the top or bottom.
Tabs: A node that can display different pages of content navigable using a familiar tab bar.
Bar: A node that adds a customizable status bar to the top or bottom of a node.

The following sections go into these types in more detail.

Pane

A :pane node is an attachment point for a pane.

{
    :type :pane
    :id nil # number or nil, optional
    :attached true # boolean or nil, optional
    :remove-on-exit false # boolean or nil, optional
}

:id

Specifies the NodeID this pane is connected to. If nil, the part of the screen occupied by this pane will just show a "disconnected" state.

:attached

If true, user input will be sent to the pane specified by :id.

:remove-on-exit

If true, when the pane specified by :id exits successfully (ie with exit code 0) or is killed using tree/kill, this pane will be removed from the layout. This works just like exiting from a shell in tmux does: the intent is to preserve that behavior for users who want it.

The value of :remove-on-exit, by default, is the value of the :remove-pane-on-exit parameter.

In other words, to make this global you can do the following:

(param/set :client :remove-pane-on-exit true)

Margins

A :margins node puts transparent margins around its child allowing the current frame to show through.

{
    :type :margins
    :cols 0 # number, optional
    :rows 0 # number, optional
    :border :rounded # border type, dynamic, optional
    :border-fg nil # color, dynamic, optional
    :border-bg nil # color, dynamic, optional
    :node {} # a node
}

:cols and :rows

These properties set the size of the node inside of the :margins node; they do not refer to the width of the margins. A value of 0 for either property means that the node will use the full space available to it in that dimension.

:border

The border style for the borders around the node.

:border-fg and :border-bg

The foreground and background color of the border.

:node

A valid layout node.

Dynamic

All dynamic properties are invoked with the same arguments:

The current value of :node.

Split

A :split node divides its visual space in two and gives it to two other nodes, rendering a line down the middle.

{
    :type :split
    :vertical false # boolean, optional
    :cells nil # int or nil, optional
    :percent nil # int or nil, optional
    :border :rounded # border type, dynamic, optional
    :border-fg nil # color, dynamic, optional
    :border-bg nil # color, dynamic, optional
    :a {} # a node
    :b {} # a node
}

:vertical

If true, the nodes are rendered on top of one another. If false, they are rendered side by side.

:cells and :percent

At most one of these can be defined. Both determine the amount of space given to the node described by :a. :cells is the number of cells along the split axis :a will be given; :percent is a percentage ([0, 100]) of the total size of the node along the split axis that will be allocated to :a.

:border

The border style to use for the dividing line.

:border-fg and :border-bg

The foreground and background color of the border.

:a and :b

Both must be valid layout nodes.

Dynamic

All dynamic properties are invoked with the same arguments:

The current value of :a.
The current value of :b.

Borders

A :borders node surrounds its child in borders and adds an optional title to the top or bottom.

{
    :type :borders
    :title nil # string or nil, dynamic, optional
    :title-bottom nil # string or nil, dynamic, optional
    :border :rounded # border type, dynamic, optional
    :border-fg nil # color, dynamic, optional
    :border-bg nil # color, dynamic, optional
    :node {} # a node
}

:title and :title-bottom

These strings will be rendered on the top and the bottom of the window, respectively.

:border

The border style for this node. :none is not supported.

:border-fg and :border-bg

The foreground and background color of the border.

:node

A valid layout node.

Actions

Dynamic

:title and :title-bottom

The dimensions of the space available to either property as a tuple, [rows, cols]. rows is always 1, but this structure is preserved for consistency.
The current value of :node.

All other properties:

The current value of :node.

Tabs

A :tabs node is a standard tab system with customizable nibs (these are also sometimes called "leaves").

{
    :type :tabs
    :active-fg nil # color, optional
    :active-bg nil # color, optional
    :inactive-fg nil # color, optional
    :inactive-bg nil # color, optional
    :bg nil # color, optional
    :bottom false # boolean, optional
    :tabs @[] # list of tabs
}

# tabs look like this:
{
    :active false # boolean, optional
    :name "" # string
    :node {} # a node
}

:active-fg, :active-bg, :inactive-fg, and :inactive-bg

These are all colors and are used to style the tab's title if the tab's :name property does not contain ANSI escape sequences, such as those generated by style/render et al.

:bg

This is the background color for the tab bar.

:bottom

If true, the tab bar will be on the bottom of the node instead of the top.

The `:tabs` property

There are some important constraints on the :tabs property:

You must provide at least one tab.
There must be exactly one tab with :active set to true.
All provided tabs must have :name fields with non-zero visual width.

Actions

Dynamic

All dynamic properties are invoked with the same arguments:

The current value of :node of the active tab of this :tabs node.

Bar

A :bar node is a status bar shown above or below the node that it contains.

{
    :type :bar
    :bottom false # boolean, optional
    :text nil # string, dynamic
    :node {} # a node
}

:bottom

If true, the bar will be on the bottom of the node instead of the top.

:text

The contents of the bar.

:node

A valid layout node.

Dynamic

The dimensions of the space available to either property as a tuple, [rows cols]. rows is always 1, but this structure is preserved for consistency.
The current value of :node.

cy documentation