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
• FileToOpen
• CommandToRun
• FloatingPaneCoordinates
• PercentOrFixed
• PluginIds
• PluginMessage
• MessageToPlugin
• NewPluginArgs
• ResizeStrategy
• Resize
• Direction
• InputMode
• HttpVerb
• RegexHighlight
• HighlightStyle
• HighlightLayer
• PaneContents
• LayoutInfo
• LayoutMetadata
• KeyWithModifier
• TabInfo
• PaneInfo
• PaneManifest
• SessionInfo
• ClientInfo
• ModeInfo
• Mouse
• CopyDestination
• PermissionType
• PermissionStatus
• WebServerStatus
• FileMetadata
• ConnectToSession
• Action
• EventType

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) => { /* terminal pane */ },
    PaneId::Plugin(id) => { /* plugin pane */ },
}
}

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

Example:

#![allow(unused)]
fn main() {
let file = FileToOpen {
    path: PathBuf::from("/home/user/project/src/main.rs"),
    line_number: Some(42),
    cwd: None,
};
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>,
}
}

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

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),  // 1 to 100
    Fixed(usize),    // 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),
    borderless: None,
};
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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),
    LeftClick(isize, usize),
    RightClick(isize, usize),
    Hold(isize, usize),
    Release(isize, usize),
    Hover(isize, usize),
}
}

CopyDestination

Specifies where text was copied to.

#![allow(unused)]
fn main() {
pub enum CopyDestination {
    Command,
    Primary,
    System,
}
}

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

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

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

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

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:

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,
    PaneRenderReportWithAnsi,
    ActionComplete,
    CwdChanged,
    AvailableLayoutInfo,
    PluginConfigurationChanged,
    HighlightClicked,
}
}

See Events for details on each event and its payload.