v0.7.1 (build 925)
Koya home

Module/hypr

Hyprland IPC client for events, commands and JSON queries.

Hyprland IPC client: connect to the compositor, listen for events, and issue commands/queries.

Import #

import * as Hypr from 'Module/hypr';

Functions #

connect
Connect to Hyprland IPC. Defaults use XDG_RUNTIME_DIR and HYPRLAND_INSTANCE_SIGNATURE from the environment.
connect(options?: { runtimeDir?: string, instanceSignature?: string }): void
on
Subscribe to a Hyprland IPC event.
  • The synthetic connection event has a connected or disconnected payload when the event socket opens or closes. The plugin reconnects automatically; register the callback before calling connect() to observe the initial connection.
on(event: string, cb: (ev: { name: string, payload: string }): void) : void
off
Unsubscribe from a Hyprland IPC event.
off(event: string, cb?: Function): void
send
Sends a raw IPC command, resolves with raw string reply.
send(command: string): Promise<string>
json
Sends a j/<topic> request and resolves with parsed JSON. Invalid JSON rejects the promise.
json(topic: string, args?: string[]): Promise<any>
workspaces
Convenience helper for json('workspaces').
workspaces(): Promise<any>
monitors
Convenience helper for json('monitors').
monitors(): Promise<any>
clients
Convenience helper for json('clients').
clients(): Promise<any>
activeworkspace
Convenience helper for json('activeworkspace').
activeworkspace(): Promise<any>
activewindow
Convenience helper for json('activewindow').
activewindow(): Promise<any>
version
Convenience helper for json('version').
version(): Promise<string>
getOption
Convenience helper for json('getoption', [name]).
getOption(name: string): Promise<any>

Example #

Connect to Hyprland, subscribe to workspace-change events, and query monitor information. This covers the typical setup for building Hyprland-aware widgets.

import * as Hypr from 'Module/hypr';
import * as Log from 'Helix/Log';

Hypr.connect();
Hypr.on('workspace', (ev) => Log.info('Workspace event: ' + ev.payload));

const mons = await Hypr.monitors();
Log.info('monitors=' + JSON.stringify(mons));

const out = await Hypr.send('version');
Log.info('hypr version: ' + out.trim());

Notes #

  • Events are polled internally and dispatched on the JS thread.
  • Each runtime has independent subscriptions, IPC settings and pending requests.
  • Command replies are read until EOF, up to 4 MiB. At most 64 requests may be pending. Connection and socket I/O waits time out after two seconds without progress.
<- Module/wsModule/pam ->