Layouts

Layouts are yaml configuration files which Zellij can load on startup. These files can describe a layout of terminal panes and plugins that Zellij will create when it loads. To load a layout with Zellij:

zellij --layout-path /path/to/your/layout_file.yaml

Example

This file:

---
direction: Vertical
parts:
  - direction: Horizontal
    split_size:
      Percent: 50
    parts:
      - direction: Vertical
        split_size:
          Percent: 50
      - direction: Vertical
        split_size:
          Percent: 50
  - direction: Horizontal
    split_size:
      Percent: 50

Will instruct Zellij to create this layout:

┌─────┬─────┐
│     │     │
├─────┤     │
│     │     │
└─────┴─────┘

Creating a layout file

A layout file is a nested tree structure. Each node describes either a pane, or a space in which its parts (children) will be created.

parts: <layout>

Layouts are composed through the optional parts section, if a layout has a non empty parts section it is a node that is split up into these respective parts.

Example:

parts:
  - direction: Vertical
    split_size:
      Percent: 50
  - direction: Vertical
    split_size:
      Percent: 50

Each node has the following fields:

direction: Horizontal / Vertical

If the node has children, they will be created as splits in this direction.

split_size: Percent: <1-100> / Fixed: <lines/columns>

This indicates either a percentage of the node's parent's space or a fixed size of columns/rows from its parent's space.

run: plugin: <plugin> / command: <command>

This is an optional instruction to either run a command, or a plugin. If indicated, instead of loading the default shell in a terminal pane, the run action will be executed.

  • plugin: </path/to/plugin.wasm>

This is an optional path to a compiled Zellij plugin. If indicated, instead of loading a terminal, this plugin will be loaded. For more information, please see the plugin documentation of this guide. In case the plugin resides in the plugin directory, specifying the name of the plugin is sufficient.

Example:

run:
  plugin: status-bar

For more information, please see the plugin documentation of this guide.

  • command: {cmd: <path/to/command> , args: <optional-arguments> }

This is an optional path to a command. If indicated, instead of loading a pane with the default shell, this command will be executed. Optionally it's arguments can be passed as a vector of strings.

Example:

run:
  command: {cmd: htop, args: ["-C"]}

Further examples

Please take a look at the default layouts that come with Zellij, or the layouts that reside in the example directory for more complete layouts.