Lua events

Events

With hl.on, you can define callbacks on events. You can register as many as you want.

hl.on("window.active", function(w)
  hl.notification.create({ text = "Window focused: " .. w.title, timeout = 5000, icon = "ok" })
end)

Or, if you’re working with events that have multiple parameters:

hl.on("workspace.move_to_monitor", function(ws, m)
  hl.notification.create({
    text = "Workspace: " .. ws.name .. " moved to a monitor at x: " .. m.position.x,
    timeout = 4000,
    icon = "ok"
  })
end)

Event list:

Event	Description	Parameters
config.props_refreshed	Emitted when a prop refresh event is executed	bool: `true` if the prop refresh event is being executed as scheduled, `false` if executed prematurely with the Lua function
config.reloaded	Emitted when the config has been reloaded and applied	None
config.unload	Emitted just before the config is unloaded and Lua state torn down, i.e. on reload or shutdown, to close or save things before they are lost	None
hyprland.shutdown	Emitted once before Hyprland exits	None
hyprland.start	Emitted once on start	None
input.keyboard.key	Emitted when a key is pressed or released	integer: XKB keycode; integer: Unix timestamp that the event occurred; integer: released (0), pressed (1), or repeated (2)
keybinds.submap	Emitted when the active submap changes. An empty string means the default submap was restored	string: Submap Name
layer.closed	Emitted when a layer surface is closed	LayerSurface
layer.opened	Emitted when a layer surface is opened	LayerSurface
monitor.added	Emitted when a monitor is connected and ready	Monitor
monitor.focused	Emitted when the active monitor changes	Monitor
monitor.layout_changed	Emitted when the monitor arrangement changes. This occurs when a monitor is added or removed, a monitor’s resolution or refresh rate is changed, or the config is reloaded with different rules	None
monitor.removed	Emitted when a monitor is disconnected and removed	Monitor
screenshare.state	Emitted when a screenshare session starts or stops	Bool: Active, Integer: Type, String: Name
window.active	Emitted when the active window changes	Window; int (focus reason)
window.bell	Emitted when a window rings the system bell, even if it’s muted	Window
window.class	Emitted when a window class changes	Window
window.close	Emitted when a window is closed. It may still be visible during its closing animation	Window
window.destroy	Emitted when a window is removed from the compositor. For windows with a close animation, fires after the animation completes	Window
window.fullscreen	Emitted when the fullscreen status of a window changes	Window
window.kill	Emitted when a window is forcefully killed via hyprctl kill	Window
window.minimize	Emitted when a window requests to change its minimized state	Window; bool: `true` if requesting minimization, `false` for unminimization
window.move_to_workspace	Emitted when a window is moved to a different workspace	Window; Workspace
window.open	Emitted when a window is fully initialized with window rules applied	Window
window.open_early	Emitted when a window is created and mapped, but before window rules are applied	Window
window.pin	Emitted when a window is pinned or unpinned	Window
window.title	Emitted when a window title changes	Window
window.update_rules	Emitted when a window’s rules are re-evaluated, e.g. when its title or class changes	Window
window.urgent	Emitted when a window requests an `urgent` state	Window
workspace.active	Emitted when the active workspace on a monitor changes	Workspace
workspace.created	Emitted when a workspace is created	Workspace
workspace.move_to_monitor	Emitted when a workspace is moved to a different monitor	Workspace; Monitor
workspace.removed	Emitted when a workspace is removed	Workspace
workspace.special_active	Emitted when the opened special workspace on a monitor changes. Workspace of nil means no special workspace is open	Workspace; Monitor

Last updated on October 14, 2026

Lua utilities