Hyprhook is a plugin for Hyprland that allows you to run scripts when specific events occur. It acts as a proxy to make event information available outside of C++ code, passing relevant data as JSON parameters to your scripts.
Explore the docs »
View Demo
·
Report Bug
·
Request Feature
Table of Contents
To build the project, ensure that the Hyprland headers are installed on your system. Then, navigate to the repository directory and run:
make allThen use hyprctl plugin load followed by the absolute path to the .so file to load, you could add this to your exec-once to load the plugin on startup
hyprpm add https://github.com/Hyprhook/Hyprhook
hyprpm enable HyprhookRefer to the Hyprland wiki on plugins, but your flake might look like this:
To configure Hyprhook, specify the script directories for each event in your Hyprland configuration file. When an event occurs, the corresponding script will be executed with the event data passed as a JSON parameter (if applicable). The available keywords are the names of the events as listed in JSON Parameters.
Important
The event 'submap' is called 'onSubmap' in the configuration file.
Example configuration snippet:
plugin {
hyprhook {
activeWindow = /path/to/your/script.sh
openWindow = /path/to/another/script.sh # Add more event-script mappings as needed
}
}Note
Ensure your scripts are executable and include the appropriate shebang (e.g., #!/bin/bash for Bash scripts). If your scripts do not execute as expected, verify that they have execute permissions and that the shebang matches the script's interpreter.
The plugin uses the following functions to generate JSON parameters for each event:
Submap Data: Returns a json with the attribut submap for the submap name changed to.Window Data: Returns JSON for a window like withhyprctl activeWindow -j.Workspace Data: Returns JSON for a workspace like withhyprctl activeWorkspace -j.Monitor Data: Returns JSON for a monitor like withhyprctl monitors -jbut for one monitor only.Vector2D Data: Returns JSON for aVector2Dobject with x and y values.SButton Data: Returns JSON for a button event (IPointer::SButtonEvent).SDown Data: Returns JSON for a touch down event (ITouch::SDownEvent).SUp Data: Returns JSON for a touch up event (ITouch::SUpEvent).
Note
If you want to know how the json looks like you can always set the script to be run to echo and see the output.
| Event | Description | Parameter (JSON) |
|---|---|---|
activeWindow |
Fired on active window change | Window data |
keyboardFocus |
Fired on keyboard focus change. Contains the newly focused surface | None |
moveWorkspace |
Fired when a workspace changes its monitor | Vector of Workspace and Monitor data |
focusedMon |
Fired on monitor focus change | Monitor data |
moveWindow |
Fired when a window changes workspace | Vector of Window and Workspace data |
openLayer |
Fired when a layer surface is mapped | None |
closeLayer |
Fired when a layer surface is unmapped | None |
openWindow |
Fired when a window is mapped | Window data |
closeWindow |
Fired when a window is unmapped | Window data |
windowUpdateRules |
Fired when a window’s rules are updated | Window data |
urgent |
Fired when a window requests urgent status | Window data |
minimize |
Fired when a window requests a minimize status change | None |
monitorAdded |
Fired when a monitor is plugged in | Monitor data |
monitorRemoved |
Fired when a monitor is unplugged | Monitor data |
createWorkspace |
Fired when a workspace is created | Workspace data |
destroyWorkspace |
Fired when a workspace is destroyed | Workspace data |
fullscreen |
Fired when a window changes fullscreen state | Window data |
changeFloatingMode |
Fired when a window changes float state | Window data |
workspace |
Fired on a workspace change (explicitly requested by a user) | Workspace data |
submap |
Fired on a submap change | Submap data |
mouseMove |
Fired when the cursor moves. Param is coordinates | Vector2D data |
mouseButton |
Fired on a mouse button press | Button event data |
mouseAxis |
Fired on a mouse axis event | None |
touchDown |
Fired on a touch down event | Touch down event data |
touchUp |
Fired on a touch up event | Touch up event data |
touchMove |
Fired on a touch motion event | None |
activeLayout |
Fired on a keyboard layout change. String pointer temporary, not guaranteed after execution of the handler finishes | None |
preRender |
Fired before a frame for a monitor is about to be rendered | Monitor data |
screencast |
Fired when the screencopy state of a client changes. Keep in mind there might be multiple separate clients | None |
render |
Fired at various stages of rendering to allow your plugin to render stuff | None |
windowtitle |
Emitted when a window title changes | Window data |
configReloaded |
Emitted after the config is reloaded | None |
preConfigReload |
Emitted before a config reload | None |
keyPress |
Emitted on a key press | None |
pin |
Emitted when a window is pinned or unpinned | Window data |
swipeBegin |
Emitted when a touchpad swipe is commenced | None |
swipeUpdate |
Emitted when a touchpad swipe is updated | None |
swipeEnd |
Emitted when a touchpad swipe is ended | None |
In case the information is wrong or outdated, please refer to Hyprland's event list.
Emacs, Neovim user here? You might be familiar with which-key.
If not, it's a plugin that displays the available keybindings in a minibuffer.
I'm horrible at remembering keybinds, so a way of showing possible keybinds is a must for me.
Hyprland has a way to give keybinds a description and a way to print configured keybinds. So the only thing we need is a way to trigger a popup with the keybinds for a specific submap.
For a simple implementation we will use eww to display things and jq to parse the JSON data coming from hyprctl.
Important
For all of this to make sense you should have given your keybinds a description in your hyprland.conf.
If you haven't done that yet, you can find more information here or do it like this:
bindd = $mainMod, C, Close Window, closeWindow| Dependency | Description |
|---|---|
eww |
A widget system to display the keybinds |
jq |
A lightweight and flexible command-line JSON processor |
JetBrains Mono Nerd Font |
A font that supports the Nerd Font icons |
Note
If you want to use a different eww config directory, you will have to change the path used in the script.
- Get the eww which-key config from ./examples/which-key/eww and place it in
~/.config/eww-which-key. - Get the which-key script from ./examples/which-key/which-key.sh and place it in your scripts directory. This example will use
~/.config/hypr/scripts. - Don't forget to make the script executable with
chmod +x ~/.config/hypr/scripts/which-key.sh. - Add the following lines to your
hyprland.conf:
plugin {
hyprhook {
onSubmap = ~/.config/hypr/scripts/which-key.sh
}
}If you want you can also bind one key to show all keybinds that are not in a submap.
Just add the following line to your hyprland.conf:
bindd = $mainMod, H, Toggle Binds Help, exec, ~/.config/hypr/scripts/which-key.sh -bContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. For details on what this means, please see the MIT License summary or refer to the LICENSE.txt file in this repository.
Ugh maybe in git :)
Project Link: https://github.com/Hyprhook/Hyprhook