Skip to content
Configuring
Core
Advanced configuration
Lua events

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
window.update_state Emitted when a window’s desktop state changes. State table has flags (e.g. pinned or floating). Nil means unchanged. Window, State table
workspace.active Emitted when the active workspace on a monitor changes Workspace
workspace.created Emitted when a workspace is created, after activating if appropriate Workspace
workspace.created_early Emitted when a workspace is created, but before it is activated 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
Lua utilities