Plugin API - Type Reference

This page documents the key data types used throughout the Zellij plugin API. These types are used as parameters and return values in plugin commands and as payloads in plugin events.

For the complete type definitions, see the zellij-tile API documentation.

All types listed here are available via use zellij_tile::prelude::*;.


Table of Contents


PaneId

Uniquely identifies a pane across the session. A pane is either a terminal or a plugin.

#![allow(unused)]
fn main() {
pub enum PaneId {
    Terminal(u32),
    Plugin(u32),
}
}

Example:

#![allow(unused)]
fn main() {
let terminal_pane = PaneId::Terminal(1);
let plugin_pane = PaneId::Plugin(0);

match pane_id {
    PaneId::Terminal(id) => {},
    PaneId::Plugin(id) => {},
}
}

FileToOpen

Specifies a file to open in the user's $EDITOR, with optional line number and working directory.

#![allow(unused)]
fn main() {
pub struct FileToOpen {
    pub path: PathBuf,
    pub line_number: Option<usize>,
    pub cwd: Option<PathBuf>,
    pub border_style: Option<BorderStyleOverride>,
}
}
FieldTypeDescription
pathPathBufPath to the file to open
line_numberOption<usize>Optional line number to jump to (if the editor supports it)
cwdOption<PathBuf>Optional working directory for the editor process
border_styleOption<BorderStyleOverride>Optional border line style for the new pane

The builder methods FileToOpen::new(path), .with_line_number(line), .with_cwd(cwd) and .with_border_style(border_style) keep working when fields are added.

Example:

#![allow(unused)]
fn main() {
let file = FileToOpen::new("/home/user/project/src/main.rs").with_line_number(42);
open_file(file, BTreeMap::new());
}

CommandToRun

Specifies a command to execute in a command pane.

#![allow(unused)]
fn main() {
pub struct CommandToRun {
    pub path: PathBuf,
    pub args: Vec<String>,
    pub cwd: Option<PathBuf>,
    pub border_style: Option<BorderStyleOverride>,
}
}
FieldTypeDescription
pathPathBufPath to the executable
argsVec<String>Command-line arguments
cwdOption<PathBuf>Optional working directory
border_styleOption<BorderStyleOverride>Optional border line style for the new pane

The builder methods CommandToRun::new(path), CommandToRun::new_with_args(path, args) and .with_border_style(border_style) are also available. When building the struct directly, end it with ..Default::default() so that it keeps compiling when fields are added.

Example:

#![allow(unused)]
fn main() {
let cmd = CommandToRun {
    path: PathBuf::from("cargo"),
    args: vec!["build".to_string(), "--release".to_string()],
    cwd: Some(PathBuf::from("/home/user/project")),
    ..Default::default()
};
open_command_pane(cmd, BTreeMap::new());
}

FloatingPaneCoordinates

Specifies the position and size of a floating pane.

#![allow(unused)]
fn main() {
pub struct FloatingPaneCoordinates {
    pub x: Option<PercentOrFixed>,
    pub y: Option<PercentOrFixed>,
    pub width: Option<PercentOrFixed>,
    pub height: Option<PercentOrFixed>,
    pub pinned: Option<bool>,
    pub borderless: Option<bool>,
    pub border_style: Option<BorderStyleOverride>,
}
}
FieldTypeDescription
xOption<PercentOrFixed>Horizontal position (columns from left)
yOption<PercentOrFixed>Vertical position (rows from top)
widthOption<PercentOrFixed>Width of the pane
heightOption<PercentOrFixed>Height of the pane
pinnedOption<bool>Whether the floating pane is pinned (stays visible when toggling floating panes)
borderlessOption<bool>Whether the pane border is hidden
border_styleOption<BorderStyleOverride>Border line style of the pane

All fields are optional. When None, Zellij uses its default placement logic.


PercentOrFixed

Specifies a dimension as either a percentage or a fixed number of rows/columns.

#![allow(unused)]
fn main() {
pub enum PercentOrFixed {
    Percent(usize),
    Fixed(usize),
}
}

Percent is a value from 1 to 100. Fixed is an absolute number of columns or rows.

Example:

#![allow(unused)]
fn main() {
let coords = FloatingPaneCoordinates {
    x: Some(PercentOrFixed::Percent(10)),
    y: Some(PercentOrFixed::Fixed(5)),
    width: Some(PercentOrFixed::Percent(80)),
    height: Some(PercentOrFixed::Fixed(20)),
    pinned: Some(true),
    ..Default::default()
};
}

PluginIds

Contains identifying information for the current plugin instance.

#![allow(unused)]
fn main() {
pub struct PluginIds {
    pub plugin_id: u32,
    pub zellij_pid: u32,
    pub initial_cwd: PathBuf,
    pub client_id: ClientId,
}
}
FieldTypeDescription
plugin_idu32Unique identifier for this plugin pane
zellij_pidu32Process ID of the Zellij server
initial_cwdPathBufWorking directory when the plugin was loaded
client_idClientIdThe client that loaded this plugin (u32)

PluginMessage

A message for communication between a plugin and its workers.

#![allow(unused)]
fn main() {
pub struct PluginMessage {
    pub name: String,
    pub payload: String,
    pub worker_name: Option<String>,
}
}
FieldTypeDescription
nameStringMessage identifier/type
payloadStringMessage content
worker_nameOption<String>Target worker name (used with post_message_to)

See Workers for Async Tasks for usage details.


MessageToPlugin

A message destined for another plugin instance (potentially launching it).

#![allow(unused)]
fn main() {
pub struct MessageToPlugin {
    pub plugin_url: Option<String>,
    pub destination_plugin_id: Option<u32>,
    pub plugin_config: BTreeMap<String, String>,
    pub message_name: String,
    pub message_payload: Option<String>,
    pub message_args: BTreeMap<String, String>,
    pub new_plugin_args: Option<NewPluginArgs>,
    pub floating_pane_coordinates: Option<FloatingPaneCoordinates>,
}
}
FieldTypeDescription
plugin_urlOption<String>URL of the target plugin (e.g., "file:/path/to/plugin.wasm")
destination_plugin_idOption<u32>ID of a specific running plugin instance
plugin_configBTreeMap<String, String>Configuration to match or provide to the target plugin
message_nameStringMessage identifier
message_payloadOption<String>Optional message content
message_argsBTreeMap<String, String>Additional key-value arguments
new_plugin_argsOption<NewPluginArgs>Configuration for launching a new plugin if none is running
floating_pane_coordinatesOption<FloatingPaneCoordinates>Position for newly launched plugin pane

NewPluginArgs

Configuration for launching a new plugin instance when the target of a message is not already running.

#![allow(unused)]
fn main() {
pub struct NewPluginArgs {
    pub should_float: Option<bool>,
    pub pane_id_to_replace: Option<PaneId>,
    pub pane_title: Option<String>,
    pub cwd: Option<PathBuf>,
    pub skip_cache: bool,
    pub should_focus: Option<bool>,
}
}
FieldTypeDescription
should_floatOption<bool>Whether the new pane should float
pane_id_to_replaceOption<PaneId>Pane to replace with the new plugin
pane_titleOption<String>Title for the new pane
cwdOption<PathBuf>Working directory for the new plugin
skip_cacheboolWhether to skip the plugin cache (force reload)
should_focusOption<bool>Whether the new pane should receive focus

ResizeStrategy

Describes how a pane should be resized, including direction and boundary behavior.

#![allow(unused)]
fn main() {
pub struct ResizeStrategy {
    pub resize: Resize,
    pub direction: Option<Direction>,
    pub invert_on_boundaries: bool,
}
}
FieldTypeDescription
resizeResizeWhether to increase or decrease the pane area
directionOption<Direction>Which border to move (None = all borders equally)
invert_on_boundariesboolIf true (default), resize inverts when hitting viewport boundaries

Resize

The direction of a resize operation.

#![allow(unused)]
fn main() {
pub enum Resize {
    Increase,
    Decrease,
}
}

Direction

A cardinal direction used for focus movement, pane movement, and resizing.

#![allow(unused)]
fn main() {
pub enum Direction {
    Left,
    Right,
    Up,
    Down,
}
}

InputMode

Describes the different input modes, which change the way keystrokes are interpreted.

#![allow(unused)]
fn main() {
pub enum InputMode {
    Normal,
    Locked,
    Resize,
    Pane,
    Tab,
    Scroll,
    EnterSearch,
    Search,
    RenameTab,
    RenamePane,
    Session,
    Move,
    Prompt,
    Tmux,
    RenameSession,
}
}
VariantDescription
NormalInput is written to the terminal, except for mode-switching shortcuts
LockedAll input goes to the terminal; all shortcuts disabled except the one to return to Normal
ResizeAllows resizing panes
PaneAllows creating, closing, and navigating between panes
TabAllows creating, closing, and navigating between tabs
ScrollAllows scrolling up and down within a pane
EnterSearchAllows typing a search needle for the scroll buffer
SearchAllows searching within a pane (superset of Scroll)
RenameTabAllows assigning a new name to a tab
RenamePaneAllows assigning a new name to a pane
SessionAllows detaching and session management
MoveAllows moving panes within a tab
PromptAllows interacting with active prompts
TmuxProvides basic tmux keybinding compatibility
RenameSessionAllows assigning a new name to the session (plugins built against 0.45 see it as RenameTab)

HttpVerb

HTTP method for web requests.

#![allow(unused)]
fn main() {
pub enum HttpVerb {
    Get,
    Post,
    Put,
    Delete,
}
}

RegexHighlight

Defines a regex-based content highlight that a plugin can apply to a terminal pane.

#![allow(unused)]
fn main() {
pub struct RegexHighlight {
    pub pattern: String,
    pub style: HighlightStyle,
    pub layer: HighlightLayer,
    pub context: BTreeMap<String, String>,
    pub on_hover: bool,
    pub bold: bool,
    pub italic: bool,
    pub underline: bool,
    pub tooltip_text: Option<String>,
}
}
FieldTypeDescription
patternStringRegex pattern to match against pane content
styleHighlightStyleColor scheme for matched text
layerHighlightLayerPriority layer for overlapping highlights
contextBTreeMap<String, String>Arbitrary data echoed back on click via HighlightClicked event
on_hoverboolIf true, highlight only renders when the cursor overlaps the match
boldboolRender matched text in bold
italicboolRender matched text in italic
underlineboolRender matched text with underline
tooltip_textOption<String>Text shown at the bottom of the pane frame when hovering over the match

HighlightStyle

Color scheme for a regex highlight. Theme-based variants reference colors from the active theme.

#![allow(unused)]
fn main() {
pub enum HighlightStyle {
    None,
    Emphasis0,
    Emphasis1,
    Emphasis2,
    Emphasis3,
    BackgroundEmphasis0,
    BackgroundEmphasis1,
    BackgroundEmphasis2,
    BackgroundEmphasis3,
    CustomRgb {
        fg: Option<(u8, u8, u8)>,
        bg: Option<(u8, u8, u8)>,
    },
    CustomIndex {
        fg: Option<u8>,
        bg: Option<u8>,
    },
}
}
VariantDescription
NoneNo color override (use with bold/italic/underline for style-only highlights)
Emphasis0..Emphasis3Foreground set to theme emphasis color 0-3, no background override
BackgroundEmphasis0..BackgroundEmphasis3Background set to theme emphasis color 0-3, foreground set to background color
CustomRgbCustom foreground and/or background as RGB tuples
CustomIndexCustom foreground and/or background as terminal color indices (0-255)

HighlightLayer

Priority layer for plugin-supplied regex highlights. Higher-priority layers take visual precedence over lower ones when highlights overlap. Built-in highlights (mouse selection, search results) always take precedence over all plugin layers.

#![allow(unused)]
fn main() {
pub enum HighlightLayer {
    Hint,
    Tool,
    ActionFeedback,
}
}
VariantPriorityDescription
HintLowestPure pattern matching (paths, URLs, IPs)
ToolMiddleBacked by runtime domain knowledge (git, docker, k8s)
ActionFeedbackHighestResult of an explicit user action (search, bookmarks)

PaneContents

The text contents of a pane, including viewport and scrollback.

#![allow(unused)]
fn main() {
pub struct PaneContents {
    pub lines_above_viewport: Vec<String>,
    pub lines_below_viewport: Vec<String>,
    pub viewport: Vec<String>,
    pub selected_text: Option<SelectedText>,
    pub cursor: Option<(usize, usize)>,
}
}
FieldTypeDescription
lines_above_viewportVec<String>Lines above the current viewport (only populated if full scrollback is requested)
lines_below_viewportVec<String>Lines below the current viewport (only populated if full scrollback is requested)
viewportVec<String>Currently visible lines
selected_textOption<SelectedText>Currently selected text range, if any
cursorOption<(usize, usize)>Cursor position (x, y) inside the viewport, if visible

Note: lines_above_viewport and lines_below_viewport are only populated when explicitly requested (e.g., with get_full_scrollback: true in get_pane_scrollback). This is for performance reasons.


LayoutInfo

Identifies a layout by its source.

#![allow(unused)]
fn main() {
pub enum LayoutInfo {
    BuiltIn(String),
    File(String, LayoutMetadata),
    Url(String),
    Stringified(String),
}
}
VariantDescription
BuiltIn(name)A built-in layout (e.g., "default", "compact", "welcome")
File(name, metadata)A layout file from the layout directory, with parsed metadata
Url(url)A layout loaded from a URL
Stringified(kdl)A raw KDL layout string

LayoutMetadata

Parsed metadata about a layout's structure.

#![allow(unused)]
fn main() {
pub struct LayoutMetadata {
    pub tabs: Vec<TabMetadata>,
    pub creation_time: String,
    pub update_time: String,
}
}
FieldTypeDescription
tabsVec<TabMetadata>Metadata for each tab defined in the layout
creation_timeStringWhen the layout was created
update_timeStringWhen the layout was last updated

KeyWithModifier

A keyboard key combined with zero or more modifier keys.

#![allow(unused)]
fn main() {
pub struct KeyWithModifier {
    pub bare_key: BareKey,
    pub key_modifiers: BTreeSet<KeyModifier>,
}
}
FieldTypeDescription
bare_keyBareKeyThe base key (e.g., BareKey::Char('a'), BareKey::Enter, BareKey::F(1))
key_modifiersBTreeSet<KeyModifier>Set of active modifiers (Ctrl, Alt, Shift, Super)

TabInfo

Information about a currently opened tab.

#![allow(unused)]
fn main() {
pub struct TabInfo {
    pub position: usize,
    pub name: String,
    pub active: bool,
    pub panes_to_hide: usize,
    pub is_fullscreen_active: bool,
    pub is_sync_panes_active: bool,
    pub are_floating_panes_visible: bool,
    pub other_focused_clients: Vec<ClientId>,
    pub other_focused_client_slots: Vec<usize>,
    pub active_swap_layout_name: Option<String>,
    pub is_swap_layout_dirty: bool,
    pub viewport_rows: usize,
    pub viewport_columns: usize,
    pub display_area_rows: usize,
    pub display_area_columns: usize,
    pub selectable_tiled_panes_count: usize,
    pub selectable_floating_panes_count: usize,
    pub tab_id: usize,
    pub has_bell_notification: bool,
    pub is_flashing_bell: bool,
    pub attention: TabAttention,
}
}
FieldTypeDescription
positionusizeThe tab's 0-indexed position
nameStringDisplay name of the tab
activeboolWhether this tab is currently focused
panes_to_hideusizeNumber of suppressed panes in this tab
is_fullscreen_activeboolWhether a pane is taking up the full display area
is_sync_panes_activeboolWhether STDIN sync is active for this tab
are_floating_panes_visibleboolWhether floating panes are visible
other_focused_clientsVec<ClientId>Other clients focused on this tab
other_focused_client_slotsVec<usize>The display color slot of each client in other_focused_clients, in the same order. Pass it to client_slot_to_colors to get that client's colors
active_swap_layout_nameOption<String>Name of the active swap layout, if any
is_swap_layout_dirtyboolWhether the user manually changed the layout
viewport_rowsusizeRow count in the viewport (excluding UI panes)
viewport_columnsusizeColumn count in the viewport (excluding UI panes)
display_area_rowsusizeTotal row count (including UI panes)
display_area_columnsusizeTotal column count (including UI panes)
selectable_tiled_panes_countusizeNumber of selectable tiled panes
selectable_floating_panes_countusizeNumber of selectable floating panes
tab_idusizeStable identifier for this tab
has_bell_notificationboolWhether this tab has an active bell notification
is_flashing_bellboolWhether this tab is currently flashing its bell
attentionTabAttentionThe most urgent attention state of the tab's panes, with counts

PaneInfo

Information about a currently open pane.

The coordinates and size fields come in two variants:

  • Pane coordinates (pane_x, pane_columns, etc.) - the entire space including frame and title
  • Content coordinates (pane_content_x, pane_content_columns, etc.) - the area taken by the pane's content only
#![allow(unused)]
fn main() {
pub struct PaneInfo {
    pub id: u32,
    pub is_plugin: bool,
    pub is_focused: bool,
    pub is_fullscreen: bool,
    pub is_floating: bool,
    pub is_suppressed: bool,
    pub is_collapsed: bool,
    pub title: String,
    pub exited: bool,
    pub exit_status: Option<i32>,
    pub is_held: bool,
    pub pane_x: usize,
    pub pane_content_x: usize,
    pub pane_y: usize,
    pub pane_content_y: usize,
    pub pane_rows: usize,
    pub pane_content_rows: usize,
    pub pane_columns: usize,
    pub pane_content_columns: usize,
    pub cursor_coordinates_in_pane: Option<(usize, usize)>,
    pub terminal_command: Option<String>,
    pub plugin_url: Option<String>,
    pub is_selectable: bool,
    pub index_in_pane_group: BTreeMap<ClientId, usize>,
    pub default_fg: Option<String>,
    pub default_bg: Option<String>,
    pub nested_session_name: Option<String>,
    pub attention: PaneAttention,
    pub command_state: CommandState,
    pub program_status: Vec<ProgramStatusRecord>,
}
}
FieldTypeDescription
idu32Pane identifier (unique within its type: terminal or plugin)
is_pluginbooltrue if plugin pane, false if terminal pane
is_focusedboolWhether this pane is focused in its layer
is_fullscreenboolWhether this pane is in fullscreen mode
is_floatingboolWhether this pane is floating
is_suppressedboolWhether this pane is suppressed (hidden but still running)
is_collapsedboolWhether this pane gave its layout space back with set_self_collapsed
titleStringDisplay title of the pane
exitedboolWhether the pane's process has exited
exit_statusOption<i32>Exit code if the process exited
is_heldboolWhether the pane is paused waiting for user input
pane_xusizeX position including frame
pane_content_xusizeX position of content area
pane_yusizeY position including frame
pane_content_yusizeY position of content area
pane_rowsusizeHeight including frame
pane_content_rowsusizeHeight of content area
pane_columnsusizeWidth including frame
pane_content_columnsusizeWidth of content area
cursor_coordinates_in_paneOption<(usize, usize)>Cursor position (x, y) relative to pane, if visible
terminal_commandOption<String>Stringified command and args (for command panes)
plugin_urlOption<String>Plugin URL (for plugin panes)
is_selectableboolWhether the user can select this pane
index_in_pane_groupBTreeMap<ClientId, usize>Pane group membership indices per client
default_fgOption<String>Default foreground color (e.g., "#00e000")
default_bgOption<String>Default background color (e.g., "#001a3a")
nested_session_nameOption<String>Name of the nested Zellij session running in this pane, if any
attentionPaneAttentionAttention state of the pane
command_stateCommandStateWhat the shell in the pane is doing: at the prompt, running a command, finished, and the last command's outcome
program_statusVec<ProgramStatusRecord>Statuses reported by programs running in the pane

Without the ReadPaneContents permission, attention and command_state arrive without the text of the commands.


PaneManifest

A dictionary of all panes in the session, indexed by tab position.

#![allow(unused)]
fn main() {
pub struct PaneManifest {
    pub panes: HashMap<usize, Vec<PaneInfo>>,
}
}
FieldTypeDescription
panesHashMap<usize, Vec<PaneInfo>>Map from tab position (0-indexed) to panes in that tab

Panes include tiled, floating, and suppressed panes.


SessionInfo

Information about a running Zellij session.

#![allow(unused)]
fn main() {
pub struct SessionInfo {
    pub name: String,
    pub tabs: Vec<TabInfo>,
    pub panes: PaneManifest,
    pub connected_clients: usize,
    pub is_current_session: bool,
    pub available_layouts: Vec<LayoutInfo>,
    pub plugins: BTreeMap<u32, PluginInfo>,
    pub web_clients_allowed: bool,
    pub web_client_count: usize,
    pub tab_history: BTreeMap<ClientId, Vec<usize>>,
    pub pane_history: BTreeMap<ClientId, Vec<PaneId>>,
    pub creation_time: Duration,
    pub attention_muted: bool,
}
}
FieldTypeDescription
nameStringSession name
tabsVec<TabInfo>All tabs in this session
panesPaneManifestAll panes in this session
connected_clientsusizeNumber of connected clients
is_current_sessionboolWhether this is the session the plugin is running in
available_layoutsVec<LayoutInfo>Layouts available in this session
pluginsBTreeMap<u32, PluginInfo>Running plugins indexed by ID
web_clients_allowedboolWhether web clients are allowed
web_client_countusizeNumber of connected web clients
tab_historyBTreeMap<ClientId, Vec<usize>>Tab focus history per client
pane_historyBTreeMap<ClientId, Vec<PaneId>>Pane focus history per client
creation_timeDurationWhen the session was created
attention_mutedboolWhether the attention status of the whole session is muted

SessionListSnapshot

A point-in-time snapshot of all sessions on the local machine, returned by get_session_list.

#![allow(unused)]
fn main() {
pub struct SessionListSnapshot {
    pub live_sessions: Vec<SessionInfo>,
    pub resurrectable_sessions: Vec<(String, Duration)>,
}
}
FieldTypeDescription
live_sessionsVec<SessionInfo>All currently running sessions
resurrectable_sessionsVec<(String, Duration)>Names of dead-but-resurrectable sessions, paired with how long ago each was last alive

HostTerminalThemeMode

The color-scheme mode reported by the host terminal via CSI 2031 / DSR 997. Delivered as the payload of the HostTerminalThemeChanged event.

#![allow(unused)]
fn main() {
pub enum HostTerminalThemeMode {
    Dark,
    Light,
}
}

ClientInfo

Information about a connected client.

#![allow(unused)]
fn main() {
pub struct ClientInfo {
    pub client_id: ClientId,
    pub pane_id: PaneId,
    pub running_command: String,
    pub is_current_client: bool,
}
}
FieldTypeDescription
client_idClientIdUnique client identifier (u32). Client ids are not reused within a session

Changed in 0.46.0: ClientId used to be a u16, and the ids of clients that left were given to new clients. | pane_id | PaneId | The pane this client is focused on | | running_command | String | Stringified command or plugin name in the focused pane | | is_current_client | bool | Whether this is the client associated with the requesting plugin |


ModeInfo

Information about the current input mode, keybindings, and session metadata. Delivered via the ModeUpdate event.

#![allow(unused)]
fn main() {
pub struct ModeInfo {
    pub mode: InputMode,
    pub base_mode: Option<InputMode>,
    pub keybinds: Vec<(InputMode, Vec<(KeyWithModifier, Vec<Action>)>)>,
    pub style: Style,
    pub capabilities: PluginCapabilities,
    pub session_name: Option<String>,
    pub editor: Option<PathBuf>,
    pub shell: Option<PathBuf>,
    pub web_clients_allowed: Option<bool>,
    pub web_sharing: Option<WebSharing>,
    pub currently_marking_pane_group: Option<bool>,
    pub is_web_client: Option<bool>,
    pub web_server_ip: Option<IpAddr>,
    pub web_server_port: Option<u16>,
    pub web_server_capability: Option<bool>,
    pub pane_frame_style: Option<PaneFrameStyle>,
    pub session_dimmed: Option<bool>,
    pub session_ancestry: Vec<String>,
    pub host_fullscreen: Option<bool>,
    pub nested_ascend_keys: Vec<KeyWithModifier>,
    pub session_ascended: Option<bool>,
    pub nested_descend_keys: Vec<KeyWithModifier>,
    pub remote_client: Option<String>,
    pub hidden_bars: HiddenBars,
}
}
FieldTypeDescription
modeInputModeCurrently active input mode
base_modeOption<InputMode>Base mode (when in a transient mode)
keybindsVec<(InputMode, Vec<(KeyWithModifier, Vec<Action>)>)>All keybindings organized by mode
styleStyleActive theme colors and styling
capabilitiesPluginCapabilitiesTerminal capabilities
session_nameOption<String>Name of the current session
editorOption<PathBuf>Configured $EDITOR
shellOption<PathBuf>Configured shell
web_clients_allowedOption<bool>Whether web clients are permitted
web_sharingOption<WebSharing>Web sharing status
currently_marking_pane_groupOption<bool>Whether pane group marking mode is active
is_web_clientOption<bool>Whether the current client is a web client
web_server_ipOption<IpAddr>Configured web server IP
web_server_portOption<u16>Configured web server port
web_server_capabilityOption<bool>Whether web server functionality is available
pane_frame_styleOption<PaneFrameStyle>The frame style currently used in this session
session_dimmedOption<bool>Whether this session's UI is dimmed because focus was handed to a nested session
session_ancestryVec<String>The names of the sessions this session is nested in, outermost first
host_fullscreenOption<bool>Whether this session's pane is fullscreen inside its host session
nested_ascend_keysVec<KeyWithModifier>Keys bound to FocusHostSession
session_ascendedOption<bool>Whether focus has been handed back up to the host session
nested_descend_keysVec<KeyWithModifier>Keys bound to FocusGuestSession
remote_clientOption<String>How this client is connected, for display (eg. "from a terminal", "from a terminal, over SSH from 10.0.0.2" or "through the web server"); None in the Zellij terminal desktop app
hidden_barsHiddenBarsThe bars currently hidden with hide_bars or the matching actions

The seven fields from pane_frame_style to nested_descend_keys relate to nested sessions and to the pane frame style. They allow plugins that render session chrome (eg. the tab-bar and status-bar) to indicate where the session sits in the nesting hierarchy and how to leave it.

style (of type Style) also has the fields border_style and floating_border_style, each a BorderStyle with the line style of every side (top, right, bottom, left) and rounded_corners: the configured border style of tiled and of floating panes.

The theme colors (style.colors, of type Styling) have one StyleDeclaration (the six colors base, background and emphasis_0 to emphasis_3, each a PaletteColor) per theme component, plus ribbon_hover: Option<StyleDeclaration>, which is None when the theme has no ribbon_hover section. To draw a hovered ribbon, use Styling::ribbon_hover_style(): it returns the hover colors that apply, including the fallback for themes without that section. Do not use ribbon_unselected.emphasis_1 as the hover fill.


PaneFrameStyle

The style used to render pane frames in the session. See the pane_frame_style option.

#![allow(unused)]
fn main() {
pub enum PaneFrameStyle {
    Full,
    Titles,
    None,
}
}
VariantDescription
FullA full border around each pane
TitlesA single title line above each pane (default)
NoneNo pane frames

StyledText

A piece of text with a set of highlighted (emphasized) character indices. Used, among others, as the payload of the HintText event. It can be turned into a Text UI component with Text::from(styled_text).

#![allow(unused)]
fn main() {
pub struct StyledText {
    pub text: String,
    pub indices: Vec<Vec<usize>>,
}
}
FieldTypeDescription
textStringThe text itself
indicesVec<Vec<usize>>Character indices to emphasize, grouped by color index

StyledText::plain(text) creates a StyledText with no highlights, and is_plain() returns true when nothing is highlighted. A StyledText can also be created from a &str or a String (with no highlights), or from a Text UI component (StyledText::from(text)).


Mouse

A mouse event that occurred while the user is focused on the plugin pane.

#![allow(unused)]
fn main() {
pub enum Mouse {
    ScrollUp(usize),
    ScrollDown(usize),
    ScrollLeft(usize),
    ScrollRight(usize),
    LeftClick(isize, usize),
    RightClick(isize, usize),
    Hold(isize, usize),
    Release(isize, usize),
    Hover(isize, usize),
    DoubleClick(isize, usize),
}
}
VariantParametersDescription
ScrollUp(n)usize - number of linesMouse wheel scrolled up
ScrollDown(n)usize - number of linesMouse wheel scrolled down
ScrollLeft(n)usize - number of columnsMouse wheel scrolled left (horizontal scroll)
ScrollRight(n)usize - number of columnsMouse wheel scrolled right (horizontal scroll)
LeftClick(line, col)isize, usize - line and columnLeft mouse button clicked
RightClick(line, col)isize, usize - line and columnRight mouse button clicked
Hold(line, col)isize, usize - line and columnMouse button held (drag)
Release(line, col)isize, usize - line and columnMouse button released
Hover(line, col)isize, usize - line and columnMouse moved without button pressed
DoubleClick(line, col)isize, usize - line and columnLeft mouse button double-clicked (not sent while mouse selection support is enabled)

The modifier keys held during a mouse event are returned by mouse_modifiers.


CopyDestination

Specifies where text was copied to.

#![allow(unused)]
fn main() {
pub enum CopyDestination {
    Command,
    Primary,
    System,
}
}
VariantDescription
CommandCopied via a configured command
PrimaryCopied to the primary selection (X11)
SystemCopied to the system clipboard

PermissionType

Permission types that plugins can request. See Permissions for details.

#![allow(unused)]
fn main() {
pub enum PermissionType {
    ReadApplicationState,
    ChangeApplicationState,
    OpenFiles,
    RunCommands,
    OpenTerminalsOrPlugins,
    WriteToStdin,
    WebAccess,
    ReadCliPipes,
    MessageAndLaunchOtherPlugins,
    Reconfigure,
    FullHdAccess,
    StartWebServer,
    InterceptInput,
    ReadPaneContents,
    RunActionsAsUser,
    WriteToClipboard,
    ReadSessionEnvironmentVariables,
}
}
VariantDescription
ReadApplicationStateRead Zellij state (panes, tabs, UI)
ChangeApplicationStateChange Zellij state and run commands
OpenFilesOpen files for editing
RunCommandsRun host commands
OpenTerminalsOrPluginsStart new terminals and plugins
WriteToStdinWrite to pane STDIN
WebAccessMake HTTP requests
ReadCliPipesControl CLI pipe input/output
MessageAndLaunchOtherPluginsSend messages to and launch other plugins
ReconfigureChange Zellij runtime configuration
FullHdAccessFull access to the host filesystem
StartWebServerStart a local web server
InterceptInputIntercept keyboard and mouse input
ReadPaneContentsRead pane viewport and scrollback contents
RunActionsAsUserExecute actions as the user
WriteToClipboardWrite to the user's clipboard
ReadSessionEnvironmentVariablesRead environment variables from session creation

PermissionStatus

Result of a permission request.

#![allow(unused)]
fn main() {
pub enum PermissionStatus {
    Granted,
    Denied,
}
}

WebServerStatus

Status of the Zellij web server.

#![allow(unused)]
fn main() {
pub enum WebServerStatus {
    Online(String),
    Offline,
    DifferentVersion(String),
}
}
VariantDescription
Online(base_url)Web server is online at the given base URL
OfflineWeb server is not running
DifferentVersion(version)Web server is running a different Zellij version

FileMetadata

Metadata about a file from filesystem events.

#![allow(unused)]
fn main() {
pub struct FileMetadata {
    pub is_dir: bool,
    pub is_file: bool,
    pub is_symlink: bool,
    pub len: u64,
}
}
FieldTypeDescription
is_dirboolWhether the path is a directory
is_fileboolWhether the path is a regular file
is_symlinkboolWhether the path is a symbolic link
lenu64File size in bytes

ConnectToSession

Configuration for switching to or creating a session.

#![allow(unused)]
fn main() {
pub struct ConnectToSession {
    pub name: Option<String>,
    pub tab_position: Option<usize>,
    pub pane_id: Option<(u32, bool)>,
    pub layout: Option<LayoutInfo>,
    pub cwd: Option<PathBuf>,
    pub switch_context: Option<SwitchContext>,
}
}
FieldTypeDescription
nameOption<String>Session name (if None, a new session with a random name is created)
tab_positionOption<usize>Tab to focus after switching
pane_idOption<(u32, bool)>Pane to focus: (id, is_plugin)
layoutOption<LayoutInfo>Layout to apply when creating a new session
cwdOption<PathBuf>Working directory for the new session
switch_contextOption<SwitchContext>Extra options for the switch (see below)

Of SwitchContext, plugins can set two fields (the others are filled in by Zellij):

FieldTypeDescription
startup_cardOption<StartupCard>Whether to show the session card on arrival: Attention (only when a pane is waiting for the user), Always or Never
disconnect_othersboolDisconnect all other clients from the target session once this client is attached

ConnectToSession implements Default, so it can be built with ..Default::default().


Action

The Action enum represents all possible Zellij actions that can be triggered programmatically via run_action. The full enum has many variants; the most commonly used ones are listed below:

VariantDescription
QuitQuit Zellij
Write { bytes, .. }Write bytes to the focused pane
WriteChars { chars }Write characters to the focused pane
SwitchToMode { input_mode }Switch input mode
Resize { resize, direction }Resize the focused pane
MoveFocus { direction }Move focus in a direction
NewPane { direction, .. }Open a new pane
NewTab { .. }Open a new tab
GoToNextTabSwitch to the next tab
GoToPreviousTabSwitch to the previous tab
GoToTab { index }Switch to a tab by index
CloseTabClose the focused tab
CloseFocusClose the focused pane
ToggleFocusFullscreenToggle focused pane fullscreen
ToggleFloatingPanesToggle floating panes visibility
DetachDetach from the session
CopyCopy selected text
PreviousSwapLayoutSwitch to previous swap layout
NextSwapLayoutSwitch to next swap layout
LaunchOrFocusPlugin { plugin, .. }Launch or focus a plugin
RenameSession { name }Rename the current session
FocusLastPaneFocus the previously focused pane
ToggleFocusNoUiFullscreenToggle fullscreen for the focused pane, covering the UI bars as well
SetPaneFrameStyle { pane_frame_style }Set the pane frame style for the session
AreFloatingPanesVisibleQuery whether floating panes are visible
SetDarkTheme / SetLightTheme / ToggleThemeSwitch between the configured dark and light themes
FocusHostSessionNested sessions: move focus to the host session
FocusGuestSessionNested sessions: descend into the guest session in the focused pane
ToggleHostFullscreenNested sessions: toggle this session's pane fullscreen in its host
ScrollToPreviousPrompt / ScrollToNextPromptJump between shell prompts in the scrollback (OSC 133)
SelectCommandAtScrollPositionSelect the command and output at the scroll position (OSC 133)
CopyLastCommandOutputCopy the last command's output to the clipboard (OSC 133)
ApplyTiledSwapLayout / ApplyFloatingSwapLayoutApply a swap layout by name
SetPaneBorderStyleSet the border line style of a pane
ToggleBars / HideBars / ShowBarsHide or show bars at runtime
CloseFocusByPaneId, ToggleFocusFullscreenByPaneId, TogglePaneEmbedOrFloatingByPaneId, TogglePanePinnedByPaneId, TogglePaneInGroupByPaneId, StartRenamePaneByPaneIdPane actions that target a specific pane
StartRenameTabByTabId, MoveTabByTabId, MoveTabToPositionTab actions that target a specific tab
MutePane, IgnorePaneOutput, WatchPane, MuteTab, MuteSession, MarkPaneSeen, MarkAllSeen, GoToNextAttentionAttention controls (see the inbox)
GoToPreviousSession / GoToNextSession / ToggleSessionMove through the session history

For the complete list, see the source code.


EventType

Discriminant enum used with subscribe and unsubscribe. Each variant corresponds to an Event variant of the same name.

#![allow(unused)]
fn main() {
pub enum EventType {
    ModeUpdate,
    TabUpdate,
    PaneUpdate,
    Key,
    Mouse,
    Timer,
    CopyToClipboard,
    SystemClipboardFailure,
    InputReceived,
    Visible,
    CustomMessage,
    FileSystemCreate,
    FileSystemRead,
    FileSystemUpdate,
    FileSystemDelete,
    PermissionRequestResult,
    SessionUpdate,
    RunCommandResult,
    WebRequestResult,
    CommandPaneOpened,
    CommandPaneExited,
    PaneClosed,
    EditPaneOpened,
    EditPaneExited,
    CommandPaneReRun,
    FailedToWriteConfigToDisk,
    ListClients,
    HostFolderChanged,
    FailedToChangeHostFolder,
    PastedText,
    ConfigWasWrittenToDisk,
    WebServerStatus,
    FailedToStartWebServer,
    BeforeClose,
    InterceptedKeyPress,
    UserAction,
    PaneRenderReport,
    ActionComplete,
    CwdChanged,
    AvailableLayoutInfo,
    PluginConfigurationChanged,
    HighlightClicked,
    CommandChanged,
    InitialKeybinds,
    HostTerminalThemeChanged,
    SoftKeyboardVisibilityChanged,
    HintText,
    ActivePaneScroll,
    MouseWithModifiers,
    NestedSessionModeUpdate,
    NestedSessionEnded,
    ContextMenu,
    ConfigChangesDropped,
    AvailableKeybindPresets,
    ConfigFileChangedSinceRead,
    PromptResult,
    SessionSuggestions,
    SessionCountsUpdate,
    FolderSessionsUpdate,
    TerminalCommandSubmitted,
    SessionPreview,
    SavedSessionPreview,
    PaneAttentionChanged,
    PromptShown,
    CommandStarted,
    CommandFinished,
    GlobalAttentionUpdate,
    SessionHistoryUpdate,
    DesktopIntegration,
    PluginSettingsEntries,
    LiveViewStateChanged,
}
}

See Events for details on each event and its payload. MouseWithModifiers is used inside Zellij only: subscribing to it is the same as subscribing to Mouse.


BorderStyleOverride

The border line style of a single pane, side by side. Used by set_pane_border_style and by the border_style field of FileToOpen, CommandToRun and FloatingPaneCoordinates. Every field left as None keeps the configured style.

#![allow(unused)]
fn main() {
pub struct BorderStyleOverride {
    pub all: Option<LineStyle>,
    pub top: Option<LineStyle>,
    pub right: Option<LineStyle>,
    pub bottom: Option<LineStyle>,
    pub left: Option<LineStyle>,
    pub rounded_corners: Option<bool>,
}

pub enum LineStyle {
    Single,
    Double,
    Heavy,
    Dashed,
    HeavyDashed,
}
}
FieldTypeDescription
allOption<LineStyle>Style for every side that does not set its own
top, right, bottom, leftOption<LineStyle>Style for one side; takes precedence over all
rounded_cornersOption<bool>Whether the corners are rounded

BorderStyleOverride implements Default. BorderStyleOverride::from_cli_string parses the same text as the command line, eg. "double" or "top:double,left:heavy,rounded".


HiddenBars

The bars currently hidden, as reported in ModeInfo.

#![allow(unused)]
fn main() {
pub enum HiddenBars {
    None,
    All,
    Named(BTreeSet<String>),
}
}
VariantDescription
NoneNo bar is hidden
AllAll bars are hidden
Named(names)The bars with these names are hidden (eg. tab-bar, status-bar, compact-bar, or a plugin alias or location)

hidden_bars.hides("tab-bar") tells whether a specific bar is hidden. The constants ALL_BARS, TAB_BAR, STATUS_BAR and COMPACT_BAR hold the built-in names.


MouseTrigger

A mouse button press, as used in mouse bindings and reset_mousebinds.

#![allow(unused)]
fn main() {
pub struct MouseTrigger {
    pub button: MouseButton,
    pub modifiers: BTreeSet<KeyModifier>,
    pub click_count: u8,
    pub target: MouseTarget,
}

pub enum MouseButton {
    Left,
    Right,
    Middle,
    ScrollUp,
    ScrollDown,
    ScrollLeft,
    ScrollRight,
}

pub enum MouseTarget {
    Any,
    Content,
    Frame,
}
}
FieldTypeDescription
buttonMouseButtonThe button (or wheel direction)
modifiersBTreeSet<KeyModifier>Modifier keys held
click_countu81 for a click, 2 for a double click
targetMouseTargetWhere the press happens: anywhere (default), in pane content, or on a pane frame

MouseTrigger::new(button) builds one, and .with_modifiers(), .with_click_count() and .with_target() change it.


PopupOptions

How a popup opened with open_plugin_popup_with_options behaves. The struct is marked #[non_exhaustive]: build it with PopupOptions::default() and the builder methods .focused(), .corner(), .capture_all_keys() and .outside_click().

#![allow(unused)]
fn main() {
pub struct PopupOptions {
    pub focused: bool,
    pub corner: Option<PopupCorner>,
    pub capture_all_keys: bool,
    pub outside_click: Option<OutsideClick>,
}

pub enum PopupCorner {
    TopLeft,
    TopRight,
    BottomLeft,
    BottomRight,
}

pub enum OutsideClick {
    Block,
    Close,
}
}
FieldTypeDefaultDescription
focusedbooltruetrue for a menu-like popup that takes key focus and replaces the user's other open menus; false for an information popup that does not take key focus
cornerOption<PopupCorner>NonePlace the popup in this corner of the screen instead of at the requested position
capture_all_keysboolfalseSend every key to the popup, including the ones bound to Zellij actions
outside_clickOption<OutsideClick>NoneWhat a click outside the popup does: Block ignores it, Close closes the popup. None means Close for focused popups and Block for the others

PromptRequest

A question to ask with prompt. It is marked #[non_exhaustive]: build it with one of the constructors below and the builder methods.

ConstructorAsks forAnswer
PromptRequest::confirm(message)Yes or noPromptResult::Confirmed(bool)
PromptRequest::choose(items)One item of a list (several with .multi())PromptValue::Choice, or PromptValue::Choices with .multi()
PromptRequest::input(message)A line of textPromptValue::Text
PromptRequest::number(message)A whole numberPromptValue::Number
PromptRequest::toggle(message)On or offPromptValue::Bool
PromptRequest::select(message, options)One option of a dropdownPromptValue::Choice
PromptRequest::menu(items)An action from a menuPromptValue::Choice with the value of the chosen item
PromptRequest::form(fields) / PromptRequest::form_spec(spec)Several fields at oncePromptValue::Form, keyed by field id
PromptRequest::notify(message)Nothing: a notice in the top right corner that does not take focusPromptValue::Bool(true) only if the user clicks it; no result if it closes otherwise
PromptRequest::info(title, message)Nothing: an information popup-

Builder methods that apply to every request:

MethodDescription
.title(title)Title shown at the top of the popup
.message(text)The question, or the text above the fields of a form (accepts a Text to color parts of it)
.timeout(duration)Close the prompt after this long; the answer is then PromptResult::TimedOut
.default(value)The initial value, and the answer used when the timeout runs out
.placement(placement)Where to open: PromptPlacement::Pane(pane_id), Center, Mouse, Cursor or Corner(corner); by default over the calling plugin's pane
.focused(bool)Whether the popup takes key focus (all elements except notify do by default)
.capture_all_keys(bool)Send every key to the popup, including the ones bound to Zellij actions
.outside_click(OutsideClick)What a click outside does; by default Close for info and Block for the others

Builder methods for specific elements: .yes(label) and .no(label) (confirm), .multi() and .selected(values) (choose), .placeholder(text), .validate(regex) and .required() (input), .min(n) and .max(n) (number), .remember(label) and .padded() (menu), and .buttons(submit, cancel) (form). Items are ChoiceItems, which can be built from a &str, a String or a (value, label) pair.

Form fields are built with FormField::input(id, label), FormField::toggle(id, label), FormField::number(id, label), FormField::select(id, label, options) and FormField::choose(id, label, options), then refined with .required(), .validate(regex), .placeholder(text), .multi(), .min(n), .max(n), .step(n) and .default_value(value). A FormSpec (FormSpec::new(fields) with .title(), .message() and .buttons()) gives the form its own title and button labels.

Example:

#![allow(unused)]
fn main() {
let request = PromptRequest::form(vec![
    FormField::input("name", "Name").required(),
    FormField::toggle("public", "Public"),
])
.title("New project")
.timeout(Duration::from_secs(60));
self.form_request = Some(prompt(request));
}

PromptResult

The answer to a prompt, delivered with the PromptResult event.

#![allow(unused)]
fn main() {
pub enum PromptResult {
    Answered(PromptValue),
    Confirmed(bool),
    Cancelled,
    TimedOut(Option<PromptValue>),
    Error(String),
}

pub enum PromptValue {
    Text(String),
    Number(i64),
    Bool(bool),
    Choice(String),
    Choices(Vec<String>),
    Form(BTreeMap<String, PromptValue>),
}
}
VariantDescription
Answered(value)The user answered; see PromptRequest for which PromptValue each element gives
Confirmed(answer)The answer to a confirm prompt
CancelledThe user dismissed the prompt
TimedOut(default)The timeout passed; carries the default value, if any
Error(message)The request was invalid or the popup could not be opened

ContextMenuTarget

What a context menu opened with open_context_menu is about.

#![allow(unused)]
fn main() {
pub enum ContextMenuTarget {
    Tab(usize),
    Bar,
}
}
VariantDescription
Tab(position)The tab at this position (0-indexed)
BarThe bar plugin that opens the menu

ContextMenuContext

What was right-clicked, delivered with the ContextMenu event together with the entries to show.

#![allow(unused)]
fn main() {
pub struct ContextMenuContext {
    pub kind: ContextMenuKind,
    pub pane_id: Option<PaneId>,
    pub pane_is_floating: bool,
    pub tab_index: Option<usize>,
    pub tab_id: Option<usize>,
    pub tab_count: usize,
    pub line: usize,
    pub column: usize,
    pub client_id: ClientId,
    pub paste_shortcut: Option<String>,
}

pub enum ContextMenuKind {
    Pane,
    PaneFrame,
    Tab,
    Bar,
}

pub enum ContextMenuEntry {
    Item {
        label: String,
        actions: Vec<ContextMenuAction>,
        toggled_label: Option<String>,
    },
    Separator,
}
}
FieldTypeDescription
kindContextMenuKindWhether a pane's content, a pane frame, a tab or a bar was clicked
pane_idOption<PaneId>The pane clicked, if any
pane_is_floatingboolWhether that pane is floating
tab_index / tab_idOption<usize>Position and id of the tab clicked, if any
tab_countusizeNumber of tabs
line / columnusizeScreen position of the click
client_idClientIdThe user who clicked
paste_shortcutOption<String>The key that pastes from the clipboard, for display

Each ContextMenuEntry::Item has a label and the actions it runs (a ContextMenuAction is either a plain Action or an action on the clicked pane or tab). For items that toggle something, Zellij picks the right label (label or toggled_label) before sending the entries, so the label received is the one to show.


PluginSettingsEntry

An entry a plugin added to the settings screen with register_settings_entry.

#![allow(unused)]
fn main() {
pub struct PluginSettingsEntry {
    pub plugin_id: u32,
    pub title: String,
}
}

The constants OPEN_PLUGIN_SETTINGS_MESSAGE ("zellij:open_plugin_settings") and OPEN_PLUGIN_SETTINGS_CLIENT_ID_ARG ("client_id") are the name and argument of the pipe message sent to the plugin when its entry is selected.


Slot

Types used by shared plugins.

#![allow(unused)]
fn main() {
pub type SlotId = u32;

pub struct Slot {
    pub id: SlotId,
    pub kind: SlotKind,
    pub configuration: BTreeMap<String, String>,
}

pub enum SlotKind {
    Pane,
    Background,
}

pub struct EventContext {
    pub slot_id: Option<SlotId>,
    pub client_id: Option<ClientId>,
}

pub enum RenderResponse {
    Nothing,
    All,
    Client(ClientId),
    Slots(Vec<SlotId>),
}
}
TypeDescription
SlotOne use of a shared plugin: a pane (SlotKind::Pane) or a background load, eg. from load_plugins (SlotKind::Background). Its id is the plugin id of that pane, and configuration is the configuration it was opened with
EventContextThe slot an event is about (for events tied to one pane, eg. Key, Mouse, PastedText, Visible, PermissionRequestResult and PluginConfigurationChanged) and the client it came from, when known
RenderResponseWhat to render after an event: nothing (default), every slot for every client, every slot as seen by one client, or specific slots

NestedSessionKeybinds

Returned by get_nested_session_keybinds.

#![allow(unused)]
fn main() {
pub type NestedSessionKeybindsResponse = Result<NestedSessionKeybinds, NestedSessionKeybindsError>;

pub struct NestedSessionKeybinds {
    pub session_path: Vec<String>,
    pub mode: InputMode,
    pub base_mode: Option<InputMode>,
    pub keybinds: KeybindsVec,
    pub keybinds_generation: u64,
}

pub enum NestedSessionKeybindsError {
    NotANestedSession,
    NotSupported,
    GuestUnresponsive,
    GuestGone,
    TooLarge,
    Timeout,
}

pub enum NestedSessionEndReason {
    Exited,
    Unresponsive,
}
}

keybinds has the same shape as the keybindings of InitialKeybinds. session_path, mode, base_mode and keybinds_generation mean the same as in NestedSessionModeUpdate.

ErrorDescription
NotANestedSessionNo nested session runs in this pane
NotSupportedThe nested session cannot report its keybindings (eg. an older Zellij version)
GuestUnresponsiveThe nested session is not responding
GuestGoneThe nested session has ended
TooLargeThe keybindings are too large to send
TimeoutNo answer arrived in time

NestedSessionEndReason is the reason given by NestedSessionEnded.


PaneAttention

The attention state of a pane: whether it is working, done, failed, waiting for the user, and so on. See the inbox. Found in PaneInfo and in the PaneAttentionChanged event.

#![allow(unused)]
fn main() {
pub struct PaneAttention {
    pub status: AttentionStatus,
    pub source: Option<AttentionSource>,
    pub text: String,
    pub detail: AttentionDetail,
    pub since_ms: u64,
    pub changed_ms: u64,
    pub seen: bool,
    pub muted: Option<MuteScope>,
    pub ignore_output: bool,
    pub watched: bool,
    pub from_watch: bool,
    pub remembered: Option<RememberedStatus>,
}

pub enum AttentionStatus {
    Idle,
    Working,
    NewOutput,
    Quiet,
    Done,
    Failed,
    NeedsYou,
}
}
FieldTypeDescription
statusAttentionStatusThe state, from least to most urgent: Idle, Working, NewOutput, Quiet, Done, Failed, NeedsYou
sourceOption<AttentionSource>What set it: ProgramStatus, Notification, Bell, CommandPane, ShellCommand, ForegroundProcess, IdleRule, Watch or UnseenOutput
textStringShort description, for display
detailAttentionDetailMore detail when known: the kind of block (BlockedKind: Permission, Question, Auth), progress, app, title, body, exit code, duration and command
since_ms / changed_msu64When the status started and last changed (milliseconds since the Unix epoch)
seenboolWhether the user has seen it
mutedOption<MuteScope>Whether it is muted, and by what: Pane, Tab or Session
ignore_outputboolWhether new output of the pane is ignored
watched / from_watchboolWhether the pane is watched, and whether this status came from the watch
rememberedOption<RememberedStatus>An earlier status kept for display (status, text, since_ms)

Related types:

  • TabAttention (in TabInfo): status, counts and muted for a whole tab.
  • AttentionCounts: the number of panes in each state (needs_you, failed, done, working, quiet, new_output) and of muted panes (muted).
  • CommandState (in PaneInfo): phase (Unknown, AtPrompt, Typing, Running, Finished), the running command and when it started, the last CommandOutcome, the cwd the shell reported, and reports_markers (whether the shell reports prompts and commands).
  • CommandOutcome (in CommandFinished): result (Succeeded, Failed or Unknown), exit_code, err, duration_ms, ended_ms and command.
  • CommandText: the text of a command and its source (Shell, Screen or Process). Left out without the ReadPaneContents permission.
  • ProgramStatusRecord (in PaneInfo): a status reported by a program in the pane, with an optional id, a state (Idle, Working, Done, Blocked or Error), kind, progress, app, title, msg and updated_ms.

All of these are defined in zellij_utils::attention. Most are also exported by zellij_tile::prelude; CommandState, CommandText and ProgramStatusRecord are not, and are reached through the fields that hold them.


GlobalAttention

The attention state of every running session on the machine, delivered with the GlobalAttentionUpdate event.

#![allow(unused)]
fn main() {
pub struct GlobalAttention {
    pub current_session: String,
    pub sessions: Vec<GlobalSessionAttention>,
    pub items: Vec<GlobalAttentionItem>,
    pub counts: AttentionCounts,
    pub status: AttentionStatus,
    pub badge_colors: Vec<(AttentionStatus, [u8; 3])>,
    pub attention_disabled: bool,
}
}
FieldTypeDescription
current_sessionStringThe session this plugin runs in
sessionsVec<GlobalSessionAttention>Each session's name, whether it is_current, and its SessionAttention (status, counts, muted, the top item and all items)
itemsVec<GlobalAttentionItem>Every pane needing attention, with its session and whether it is_current. Each AttentionItem has the pane_id, tab_id, tab_name, pane_title and PaneAttention
countsAttentionCountsTotals across all sessions
statusAttentionStatusThe most urgent status across all sessions
badge_colorsVec<(AttentionStatus, [u8; 3])>The configured RGB color of each status
attention_disabledboolWhether attention tracking is turned off in the configuration

SessionHistoryInfo

A user's session history, delivered with the SessionHistoryUpdate event.

#![allow(unused)]
fn main() {
pub struct SessionHistoryInfo {
    pub current: String,
    pub previous: Option<String>,
    pub back: Vec<String>,
    pub forward: Vec<String>,
    pub arrived_from: Option<String>,
    pub arrival: Option<SessionArrival>,
    pub arrived_at_ms: u64,
}

pub enum SessionArrival {
    Switch,
    Toggle,
    Back,
    Forward,
    Attention { pane_id: PaneId },
}
}
FieldTypeDescription
currentStringThe current session
previousOption<String>The session the user would toggle back to
back / forwardVec<String>Sessions to go back or forward to
arrived_fromOption<String>The session the user came from
arrivalOption<SessionArrival>How the user arrived: a switch, a toggle, back, forward, or by following a pane that needed attention
arrived_at_msu64When the user arrived

SessionTerminalRequest

What to open in the Zellij terminal desktop app, used by request_session_terminal.

#![allow(unused)]
fn main() {
pub struct SessionTerminalRequest {
    pub session_name: Option<String>,
    pub new_window: bool,
    pub pane_id: Option<PaneId>,
    pub layout: Option<LayoutInfo>,
    pub cwd: Option<PathBuf>,
}
}
FieldTypeDescription
session_nameOption<String>The session to open; None creates a new session
new_windowboolOpen a new window even if one already shows this session
pane_idOption<PaneId>Pane to focus
layoutOption<LayoutInfo>Layout for a new session
cwdOption<PathBuf>Working directory for a new session

SessionTerminalRequest::existing(session_name, pane_id, new_window) and SessionTerminalRequest::new_session(session_name, layout, cwd) build the two common cases.


SessionSuggestions

Ranked sessions, delivered with the SessionSuggestions event. See session suggestions.

#![allow(unused)]
fn main() {
pub struct SessionSuggestions {
    pub folder: Option<String>,
    pub branch: Option<String>,
    pub columns: Vec<SessionSuggestionColumn>,
    pub suggestions: Vec<SessionSuggestion>,
    pub command_submitted: bool,
    pub from_script: bool,
    pub desktop_app_running: bool,
    pub desktop_window_sessions: Vec<String>,
}

pub struct SessionSuggestion {
    pub name: String,
    pub is_running: bool,
    pub last_used_secs_ago: u64,
    pub created_secs_ago: u64,
    pub folder: Option<String>,
    pub folder_relation: FolderRelation,
    pub repo: Option<String>,
    pub branch: Option<String>,
    pub facts: BTreeMap<String, String>,
    pub tier: Option<u32>,
    pub matching_columns: Vec<String>,
    pub script_label: Option<String>,
    pub tabs: Vec<SessionPreviewTab>,
    pub connected_clients: usize,
}
}

folder and branch describe where the user is now. Each suggestion's folder_relation is Here, Subfolder or Other relative to that folder. columns lists the extra facts (each with a fact key and a title) to show for each suggestion, read with suggestion.fact_value(fact). desktop_window_sessions lists the sessions already open in a desktop window.

The related events carry two smaller types:

#![allow(unused)]
fn main() {
pub struct SessionCounts {
    pub running: u32,
    pub resumable_matching: u32,
}

pub struct FolderSessions {
    pub folder: String,
    pub running: Vec<String>,
    pub resumable: Vec<String>,
    pub full_match_running: Vec<String>,
}
}

SessionPreview

The contents of another session, delivered with the SessionPreview and SavedSessionPreview events.

#![allow(unused)]
fn main() {
pub struct SessionPreview {
    pub session_name: String,
    pub tab_index: Option<usize>,
    pub active_tab_index: Option<usize>,
    pub tab_names: Vec<String>,
    pub contents: String,
    pub pane_count: usize,
    pub connected_clients: usize,
    pub error: Option<String>,
    pub tabs: Vec<SessionPreviewTab>,
    pub pane_id: Option<(u32, bool)>,
    pub anchor_line: Option<usize>,
}

pub struct SessionPreviewTab {
    pub name: String,
    pub active: bool,
    pub panes: Vec<SessionPreviewPane>,
}

pub struct SessionPreviewPane {
    pub id: u32,
    pub is_plugin: bool,
    pub title: String,
    pub focused: bool,
    pub contents: Option<String>,
}

pub enum PreviewAnchor {
    Bottom,
    LastCommandOutput,
    NewOutputStart,
}

pub struct SavedSessionPreview {
    pub session_name: String,
    pub folder: Option<String>,
    pub tabs: Vec<SavedTabPreview>,
    pub error: Option<String>,
}

pub struct SavedTabPreview {
    pub name: String,
    pub focused: bool,
    pub panes: Vec<SavedPanePreview>,
}

pub struct SavedPanePreview {
    pub title: Option<String>,
    pub command: Option<String>,
    pub cwd: Option<String>,
    pub contents: Option<String>,
    pub focused: bool,
}
}

contents is the screen of the previewed pane (the requested one, or the focused pane of the tab), including its ANSI color codes, and error is set when the preview could not be made. With an anchor, anchor_line is the line of contents the anchor points at. PreviewAnchor chooses where a pane preview starts: the bottom of the pane, the output of the last command, or the start of output the user has not seen yet.


LiveView

A live view of another pane inside a plugin, set with set_live_view.

#![allow(unused)]
fn main() {
pub struct LiveView {
    pub target: PaneAddress,
    pub x: usize,
    pub y: usize,
    pub cols: usize,
    pub rows: usize,
    pub resize_allowed: Option<bool>,
    pub view_only: bool,
}

pub struct PaneAddress {
    pub host: Option<HostId>,
    pub session: String,
    pub pane_id: PaneId,
}
}
FieldTypeDescription
targetPaneAddressThe pane to show: its session and pane_id. host is None for this machine. An empty session shows nothing
x, y, cols, rowsusizeWhere in the plugin's content area to show it
resize_allowedOption<bool>Whether the view may resize the program in the mirrored pane to its own size; None uses the mirror_resizes_source_pane option
view_onlyboolIf true, the view never takes input

LiveView::new(target, x, y, cols, rows) builds one with the defaults, and PaneAddress::local(session, pane_id) builds a target on this machine.

The state reported by LiveViewStateChanged uses these types:

#![allow(unused)]
fn main() {
pub enum MirrorState {
    NoTarget,
    Connecting,
    Live,
    Closed(MirrorClosedReason),
}

pub enum MirrorClosedReason {
    PaneClosed,
    PaneNotFound,
    SessionEnding,
    Rejected,
    VersionMismatch,
    UnsupportedHost,
    ConnectionFailed,
    ConnectionLost,
    ProtocolError,
    ContainsViewer,
}

pub enum LiveViewRelease {
    Key,
    ClickOutside,
    FocusLost,
    Plugin,
    Cleared,
    NotAllowed,
}
}

LiveViewRelease tells why input went back to the plugin: the release key, a click outside the view, focus moving away, the plugin, the view being removed or replaced, or the capture not being allowed.


SettingKey

Identifies one configuration setting, for the commands under editing the configuration. There is one variant per setting (eg. SettingKey::Theme, SettingKey::MouseMode, SettingKey::FrameRoundedCorners).

MethodDescription
key.id()The setting's full name, eg. "theme" or "ui.pane_frames.rounded_corners"
SettingKey::from_id(id)The key for a full name
key.kdl_name()The name of the setting's KDL node
key.requires_restart()Whether a change only takes effect after a restart
key.value_shape()The kind of value: Flag, Number, Decimal, Text, List or Colour
SettingKey::all()Every key

ConfigSnapshot

The configuration as returned by read_config.

#![allow(unused)]
fn main() {
pub struct ConfigSnapshot {
    pub settings: Vec<ConfigSettingState>,
    pub config_file_path: Option<String>,
    pub backup_file_path: Option<String>,
    pub pending_restart_settings: Vec<SettingKey>,
    pub theme_names: Vec<String>,
    pub plugin_aliases: Vec<String>,
    pub load_plugins: Vec<String>,
    pub env_vars: Vec<String>,
    pub context_menu_items: Vec<String>,
    pub blocks: ConfigBlocks,
    pub saved_blocks: ConfigBlocks,
    pub default_blocks: ConfigBlocks,
    pub keybindings: Vec<KeybindingEntry>,
    pub keybinds: KeybindsSelectionSnapshot,
    pub mousebindings: Vec<MousebindingEntry>,
    pub font_families: Vec<String>,
}

pub struct ConfigSettingState {
    pub key: SettingKey,
    pub saved_value: Option<String>,
    pub current_value: Option<String>,
    pub set_in_file: bool,
}
}
FieldDescription
settingsEach setting's saved and current value (a setting is unsaved when they differ), and whether it is set in the file
config_file_path / backup_file_pathThe configuration file and its backup
pending_restart_settingsChanged settings that only take effect after a restart
theme_names, plugin_aliases, load_plugins, env_vars, context_menu_itemsNames available for display
blocks, saved_blocks, default_blocksThe current, saved and default configuration blocks (ConfigBlocks: plugin aliases, load_plugins, env, context menu sections and themes)
keybindingsEvery keybinding (KeybindingEntry: mode, key, actions, where it comes from, and whether it is unbound or unsaved)
keybindsThe selected keybinding preset and its values (KeybindsSelectionSnapshot)
mousebindingsEvery mouse binding (MousebindingEntry), like keybindings
font_familiesFont families available to the Zellij terminal

snapshot.setting(key) finds one setting and snapshot.unsaved_count() counts the unsaved ones.


KeybindPresetInfo

A keybinding preset, delivered with the AvailableKeybindPresets event.

#![allow(unused)]
fn main() {
pub struct KeybindPresetInfo {
    pub name: String,
    pub display_name: String,
    pub description: Option<String>,
    pub source: KeybindPresetSource,
    pub placeholders: Vec<String>,
    pub path: Option<String>,
    pub examples: Vec<(String, String)>,
}

pub enum KeybindPresetSource {
    BuiltIn,
    Folder,
    File,
}

pub struct KeybindPresetWithError {
    pub name: String,
    pub path: String,
    pub error: String,
}
}

placeholders are the names of the values the preset lets the user choose, and examples are pairs of keys and what they do, from the preset's header, for display. KeybindPresetWithError describes a preset file that could not be read.