RAGS - v1.11.0
    Preparing search index...

    Class Hyprland

    Hyprland Compositor Service

    Service for interacting with the Hyprland compositor via its IPC socket.

    Lifecycle:

    1. Construction - Connect to Hyprland IPC sockets
    2. Initialization - Load initial state (monitors, workspaces, clients)
    3. Ready - Watch socket for events and update state
    4. Disposal - Close sockets and cleanup state

    event - Emitted for every Hyprland event (eventType: string, params: string)

    urgent-window - Emitted when window becomes urgent (address: string)

    submap - Emitted on submap change (submapName: string)

    keyboard-layout - Emitted on layout change (deviceName: string, layoutName: string)

    monitor-added - Emitted when monitor is added (monitorName: string)

    monitor-removed - Emitted when monitor is removed (monitorName: string)

    workspace-added - Emitted when workspace is created (workspaceId: string)

    workspace-removed - Emitted when workspace is destroyed (workspaceId: string)

    client-added - Emitted when window is opened (address: string)

    client-removed - Emitted when window is closed (address: string)

    fullscreen - Emitted on fullscreen state change (isFullscreen: boolean)

    screencast - Emitted on screencast change (state: boolean, owner: number, target: string)

    activespecial - Emitted on special workspace change (workspaceName: string, monitorName: string)

    pin - Emitted on window pin change (address: string, pinned: boolean)

    minimized - Emitted on window minimize change (address: string, minimized: boolean)

    bell - Emitted on window bell (address: string)

    configreloaded - Emitted when config is reloaded

    empty - Emitted when workspace becomes empty (workspaceId: string)

    kill - Emitted when window is killed (address: string)

    changed - Emitted when any state changes

    Hierarchy (View Summary)

    Implements

    Index

    Accessors

    active clients isDisposed monitors workspaces

    Constructors

    constructor

    Methods

    bind changed connect diffBind disconnectAll dispatchLegacy dispose emit eval getClient getGdkMonitor getMonitor getWorkspace message messageAsync retryWithBackoff trackConnection updateProperty import pspec register

    Properties

    dispatch

    Accessors

    • get isDisposed(): boolean

      Check if service has been disposed

      Returns boolean

    Constructors

    Methods

    • Creates a Binding for a property on this service.

      Type Parameters

      • Prop extends
            | "isDisposed"
            | "$signals"
            | "dispatch"
            | "active"
            | "monitors"
            | "workspaces"
            | "clients"

      Parameters

      • prop: Prop

        The property to bind

      Returns Binding<Hyprland, Prop, Hyprland[Prop]>

      A Binding that can be used in widget constructors

      const label = Widget.Label({
          label: audio.bind('volume').as(v => `${Math.round(v * 100)}%`),
      });

    • Notifies listeners that a property changed and emits the 'changed' signal.

      Parameters

      • property: string

        The property name that changed

      Returns void

    • Connects a callback to a signal on this service.

      Parameters

      • signal: string = 'changed'

        The signal name (defaults to 'changed')

      • callback: (_: this, ...args: any[]) => void

        The callback to invoke when the signal is emitted

      Returns number

      The signal connection ID

    • Creates an incremental list binding that reuses existing widgets.

      Instead of recreating all widgets on every update, this method caches widgets by a key function and only creates new widgets for new items, destroying widgets for removed items.

      Type Parameters

      • Item
      • Prop extends
            | "isDisposed"
            | "$signals"
            | "dispatch"
            | "active"
            | "monitors"
            | "workspaces"
            | "clients"

      Parameters

      • prop: Prop

        The property containing the item array

      • opts: {
            create: (item: Item) => Widget;
            key: (item: Item) => string | number;
            update?: (widget: Widget, item: Item) => void;
        }

        Key extractor, widget factory, and optional update callback

      Returns Binding<Hyprland, Prop, Widget[]>

      A Binding that produces an array of widgets

      const children = audio.diffBind('speakers', {
          key: (s) => s.name,
          create: (s) => Widget.Label({ label: s.description }),
          update: (w, s) => { w.label = s.description; },
      });

    • Clean up all tracked signal connections Call this in service-specific dispose implementations

      Returns void

    • Runs a legacy text-protocol dispatch command (e.g. workspace 1), translating it to the Lua dispatcher API.

      Parameters

      • command: string

        A legacy dispatcher invocation without the dispatch prefix

      Returns Promise<string>

      Hyprland 0.55 removed the text dispatch protocol. Use the typed Hyprland.dispatch API instead.

    • Emits a signal, warning if the signal was not registered via Service.register.

      The warning is cheap (a Set lookup per emit) and helps catch typos and missing signal declarations that silently break .bind().

      Parameters

      • signal: string
      • ...args: any[]

      Returns void

    • Evaluates a raw Lua string via the command socket's eval request. Returns ok or the raised error.

      Parameters

      • lua: string

        The Lua source to execute

      Returns Promise<string>

    • Retrieves a client by its hex address.

      Parameters

      • address: string

        The client address (e.g. "0x...")

      Returns Client | undefined

      The Client data or undefined

    • Returns the GDK monitor corresponding to a Hyprland monitor ID.

      Parameters

      • id: number

        The Hyprland monitor ID

      Returns Monitor | null

      The Gdk.Monitor or null

    • Retrieves a monitor by its numeric ID.

      Parameters

      • id: number

        The monitor ID

      Returns Monitor | undefined

      The Monitor data or undefined

    • Sends a synchronous IPC command to Hyprland.

      Parameters

      • cmd: string

        The Hyprland IPC command string (e.g. "j/monitors")

      Returns string

      The response string

    • Retry a DBus operation with exponential backoff

      Type Parameters

      • T

      Parameters

      • operation: () => Promise<T>
      • maxRetries: number = 3
      • baseDelay: number = 100

      Returns Promise<T>

    • Track a signal connection for automatic cleanup

      Parameters

      • emitter: Object

        The object the signal is connected to (defaults to this)

      • id: number

        The signal connection ID

      Returns void

    • Track a signal connection for automatic cleanup

      Parameters

      • id: number

        The signal connection ID

      Returns void

    • Updates a property value and emits a notify signal if the value changed.

      Performs a deep equality check via JSON serialization to avoid unnecessary notifications.

      Parameters

      • prop: string

        The property name in kebab-case

      • value: unknown

        The new value

      Returns void

    • Dynamically imports a built-in service by name.

      Type Parameters

      • S extends keyof Services

      Parameters

      • service: S

        The service name to import

      Returns Promise<Services[S]>

      The default export of the service module

      const Audio = await Service.import('audio');
      const Battery = await Service.import('battery');

    • Creates a GObject property specification.

      Parameters

      • name: string

        The property name in kebab-case

      • type: PspecType = 'jsobject'

        The property type (defaults to 'jsobject')

      • handle: PspecFlag = 'r'

        The access flag: 'r', 'w', or 'rw' (defaults to 'r')

      Returns ParamSpec<unknown>

      A GObject.ParamSpec

    • Registers a GObject subclass with signals and properties.

      Parameters

      • service: new (...args: any[]) => Object

        The class constructor to register

      • Optionalsignals: { [signal: string]: PspecType[] }

        Map of signal names to their parameter types

      • Optionalproperties: { [prop: string]: [type?: PspecType, handle?: PspecFlag] }

        Map of property names to [type, accessFlag] tuples

      Returns void

    Properties

    dispatch: {
        cursor: {
            move: (opts: { x: number; y: number }) => Promise<string>;
            moveToCorner: (
                opts: { corner: number; window?: string },
            ) => Promise<string>;
        };
        dpms: (
            opts: { action?: string; monitor?: string | number },
        ) => Promise<string>;
        event: (str: string) => Promise<string>;
        exec: (cmd: string, rules?: Record<string, LuaValue>) => Promise<string>;
        execRaw: (cmd: string) => Promise<string>;
        exit: () => Promise<string>;
        focus: (opts: FocusOpts) => Promise<string>;
        forceIdle: (seconds: number) => Promise<string>;
        global: (name: string) => Promise<string>;
        group: {
            active: (opts: { index: number; window?: string }) => Promise<string>;
            lock: (opts?: ActionOpts) => Promise<string>;
            lockActive: (opts?: { action?: string }) => Promise<string>;
            moveWindow: (
                opts: { forward?: boolean; window?: string },
            ) => Promise<string>;
            next: (opts?: { window?: string }) => Promise<string>;
            prev: (opts?: { window?: string }) => Promise<string>;
            toggle: (opts?: { window?: string }) => Promise<string>;
        };
        layout: (message: string) => Promise<string>;
        noOp: () => Promise<string>;
        raw: (luaExpr: string) => Promise<string>;
        submap: (name: string) => Promise<string>;
        window: {
            alterZorder: (
                opts: { mode: string; window?: string },
            ) => Promise<string>;
            center: (opts?: { window?: string }) => Promise<string>;
            clearTags: (opts?: { window?: string }) => Promise<string>;
            close: (window?: string) => Promise<string>;
            drag: () => Promise<string>;
            float: (opts?: ActionOpts) => Promise<string>;
            fullscreen: (
                opts?: { action?: string; mode?: string; window?: string },
            ) => Promise<string>;
            fullscreenState: (
                opts: {
                    action?: string;
                    client?: string;
                    internal?: string;
                    window?: string;
                },
            ) => Promise<string>;
            kill: (window?: string) => Promise<string>;
            move: (opts: WindowMoveOpts) => Promise<string>;
            pin: (opts?: ActionOpts) => Promise<string>;
            pseudo: (opts?: ActionOpts) => Promise<string>;
            resize: (
                opts?: {
                    keep_aspect_ratio?: boolean;
                    relative?: boolean;
                    window?: string;
                    x?: number;
                    y?: number;
                },
            ) => Promise<string>;
            setProp: (
                opts: { prop: string; value: LuaValue; window?: string },
            ) => Promise<string>;
            signal: (
                opts: { signal: string | number; window?: string },
            ) => Promise<string>;
            swap: (
                opts: {
                    direction?: string;
                    next?: boolean;
                    prev?: boolean;
                    target?: string;
                },
            ) => Promise<string>;
            tag: (opts: { tag: string; window?: string }) => Promise<string>;
            toggleSwallow: () => Promise<string>;
        };
        workspace: {
            move: (
                opts: { monitor: string | number; workspace?: string },
            ) => Promise<string>;
            rename: (opts: { name?: string; workspace: string }) => Promise<string>;
            swapMonitors: (
                opts: { monitor1: string | number; monitor2: string | number },
            ) => Promise<string>;
            toggleSpecial: (name?: string) => Promise<string>;
        };
    } = ...

    Typed, Lua-native dispatch API mirroring Hyprland's hl.dsp.* dispatchers (Hyprland 0.55+). Example: hyprland.dispatch.focus({ workspace: '3' }).

    Type Declaration

    • cursor: {
          move: (opts: { x: number; y: number }) => Promise<string>;
          moveToCorner: (
              opts: { corner: number; window?: string },
          ) => Promise<string>;
      }
      • move: (opts: { x: number; y: number }) => Promise<string>

        Move the cursor to an absolute coordinate.

      • moveToCorner: (opts: { corner: number; window?: string }) => Promise<string>

        Move the cursor to a corner of the window (corner 0-3).

    • dpms: (opts: { action?: string; monitor?: string | number }) => Promise<string>

      Toggle monitors on/off.

    • event: (str: string) => Promise<string>

      Send an event to socket2.

    • exec: (cmd: string, rules?: Record<string, LuaValue>) => Promise<string>

      Execute a command via sh -c. Optional window rules table.

    • execRaw: (cmd: string) => Promise<string>

      Execute a raw command without sh -c.

    • exit: () => Promise<string>

      Quit Hyprland. Prefer hyprshutdown.

    • focus: (opts: FocusOpts) => Promise<string>

      Move focus (by direction, monitor, workspace, window, etc.).

    • forceIdle: (seconds: number) => Promise<string>

      Set elapsed time for all idle timers.

    • global: (name: string) => Promise<string>

      Activate a D-Bus global shortcut.

    • group: {
          active: (opts: { index: number; window?: string }) => Promise<string>;
          lock: (opts?: ActionOpts) => Promise<string>;
          lockActive: (opts?: { action?: string }) => Promise<string>;
          moveWindow: (
              opts: { forward?: boolean; window?: string },
          ) => Promise<string>;
          next: (opts?: { window?: string }) => Promise<string>;
          prev: (opts?: { window?: string }) => Promise<string>;
          toggle: (opts?: { window?: string }) => Promise<string>;
      }
      • active: (opts: { index: number; window?: string }) => Promise<string>

        Focus a window in a group by index.

      • lock: (opts?: ActionOpts) => Promise<string>

        Lock a group.

      • lockActive: (opts?: { action?: string }) => Promise<string>

        Lock the active group.

      • moveWindow: (opts: { forward?: boolean; window?: string }) => Promise<string>

        Move a window within the group order.

      • next: (opts?: { window?: string }) => Promise<string>

        Focus the next window in a group.

      • prev: (opts?: { window?: string }) => Promise<string>

        Focus the previous window in a group.

      • toggle: (opts?: { window?: string }) => Promise<string>

        Toggle a group.

    • layout: (message: string) => Promise<string>

      Send a layout message string to the active layout.

    • noOp: () => Promise<string>

      Does nothing; useful for conditional binds.

    • raw: (luaExpr: string) => Promise<string>

      Escape hatch: dispatch a raw hl.dsp.* expression string.

    • submap: (name: string) => Promise<string>

      Switch to a submap.

    • window: {
          alterZorder: (
              opts: { mode: string; window?: string },
          ) => Promise<string>;
          center: (opts?: { window?: string }) => Promise<string>;
          clearTags: (opts?: { window?: string }) => Promise<string>;
          close: (window?: string) => Promise<string>;
          drag: () => Promise<string>;
          float: (opts?: ActionOpts) => Promise<string>;
          fullscreen: (
              opts?: { action?: string; mode?: string; window?: string },
          ) => Promise<string>;
          fullscreenState: (
              opts: {
                  action?: string;
                  client?: string;
                  internal?: string;
                  window?: string;
              },
          ) => Promise<string>;
          kill: (window?: string) => Promise<string>;
          move: (opts: WindowMoveOpts) => Promise<string>;
          pin: (opts?: ActionOpts) => Promise<string>;
          pseudo: (opts?: ActionOpts) => Promise<string>;
          resize: (
              opts?: {
                  keep_aspect_ratio?: boolean;
                  relative?: boolean;
                  window?: string;
                  x?: number;
                  y?: number;
              },
          ) => Promise<string>;
          setProp: (
              opts: { prop: string; value: LuaValue; window?: string },
          ) => Promise<string>;
          signal: (
              opts: { signal: string | number; window?: string },
          ) => Promise<string>;
          swap: (
              opts: {
                  direction?: string;
                  next?: boolean;
                  prev?: boolean;
                  target?: string;
              },
          ) => Promise<string>;
          tag: (opts: { tag: string; window?: string }) => Promise<string>;
          toggleSwallow: () => Promise<string>;
      }
      • alterZorder: (opts: { mode: string; window?: string }) => Promise<string>

        Alter a window's z-order (mode: "top" or "bottom").

      • center: (opts?: { window?: string }) => Promise<string>

        Center the current window.

      • clearTags: (opts?: { window?: string }) => Promise<string>

        Clear all tags from a window.

      • close: (window?: string) => Promise<string>

        Gracefully request the window to close.

      • drag: () => Promise<string>

        Begin an interactive drag (mouse binds).

      • float: (opts?: ActionOpts) => Promise<string>

        Set a window's floating state (action: toggle/true/false).

      • fullscreen: (opts?: { action?: string; mode?: string; window?: string }) => Promise<string>

        Set a window's fullscreen state.

      • fullscreenState: (
            opts: {
                action?: string;
                client?: string;
                internal?: string;
                window?: string;
            },
        ) => Promise<string>

        Set a window's fullscreen state with internal/client precision.

      • kill: (window?: string) => Promise<string>

        Kill the window's process with SIGKILL.

      • move: (opts: WindowMoveOpts) => Promise<string>

        Move a window (direction/workspace/monitor/coords/group).

      • pin: (opts?: ActionOpts) => Promise<string>

        Pin a window across workspaces.

      • pseudo: (opts?: ActionOpts) => Promise<string>

        Set a window's pseudotiling state.

      • resize: (
            opts?: {
                keep_aspect_ratio?: boolean;
                relative?: boolean;
                window?: string;
                x?: number;
                y?: number;
            },
        ) => Promise<string>

        Resize a window, or begin an interactive resize with no args.

      • setProp: (opts: { prop: string; value: LuaValue; window?: string }) => Promise<string>

        Set a window property.

      • signal: (opts: { signal: string | number; window?: string }) => Promise<string>

        Send a POSIX signal to the window's process.

      • swap: (
            opts: {
                direction?: string;
                next?: boolean;
                prev?: boolean;
                target?: string;
            },
        ) => Promise<string>

        Swap the active window with another.

      • tag: (opts: { tag: string; window?: string }) => Promise<string>

        Tag a window.

      • toggleSwallow: () => Promise<string>

        Toggle all swallowed windows visible.

    • workspace: {
          move: (
              opts: { monitor: string | number; workspace?: string },
          ) => Promise<string>;
          rename: (opts: { name?: string; workspace: string }) => Promise<string>;
          swapMonitors: (
              opts: { monitor1: string | number; monitor2: string | number },
          ) => Promise<string>;
          toggleSpecial: (name?: string) => Promise<string>;
      }
      • move: (opts: { monitor: string | number; workspace?: string }) => Promise<string>

        Move a workspace to a monitor.

      • rename: (opts: { name?: string; workspace: string }) => Promise<string>

        Rename a workspace.

      • swapMonitors: (
            opts: { monitor1: string | number; monitor2: string | number },
        ) => Promise<string>

        Swap the current workspaces of two monitors.

      • toggleSpecial: (name?: string) => Promise<string>

        Toggle a named special workspace.

    Settings

    Member Visibility

    On This Page

    Accessors
    Constructors
    Methods
    Properties