RippleFX for Hyprland

Click feedback that actually looks good. RippleFX draws animated rings under your cursor whenever you click – perfect for screen sharing, screencasts, or live demos on Hyprland.

Features

• 🔁 Smooth ring animation – concentric circles that expand and fade elegantly.
• 🎨 Fully configurable – tweak radius, duration, colour, ring count, spacing, and opacity with CLI flags or environment variables.
• 🧵 Non-blocking – the helper bind does not steal your mouse clicks.
• ⚙️ Tiny footprint – pure C with GTK layer-shell; no compositor patches required.

Requirements

Install the GTK stack and build tools:

• gtk3
• gtk-layer-shell
• cairo
• glib2 / gio
• pkgconf
• gcc, make

Getting Started

git clone https://github.com/TKasperczyk/ripple.git
cd ripple
make

Optional: install binaries system-wide

sudo make install             # or:
./install.sh                  # builds, installs, then offers to patch your Hyprland config

install.sh detects the original user when executed via sudo and appends a suggested binding if you agree.

Running the daemon

Launch the overlay (customise to taste):

ripple-daemon \
  --size 140 \
  --rings 4 \
  --ring-gap 12 \
  --line-width 3 \
  --duration 900 \
  --color '#66BBFF' \
  --alpha 0.4 &

Then register the trigger in your Hyprland config (the installer can do this for you):

bindn = ,mouse:272,exec,ripple-trigger   # left click
bindn = ,mouse:273,exec,ripple-trigger   # right click (optional)
bindn = ,mouse:274,exec,ripple-trigger   # middle click (optional)

Reload Hyprland (hyprctl reload) and enjoy the ripples.

Configuration Reference

CLI options (ripple-daemon)

Flag	Description	Default
-s, --size PIXELS	Maximum ripple radius	120
--start-radius PIXELS	Initial radius	12
-d, --duration MS	Animation duration (ms)	450
-w, --line-width PIXELS	Stroke width	4
--ring-gap PIXELS	Gap between rings	6
--rings COUNT	Number of rings	3
-a, --alpha VALUE	Starting opacity (0–1)	0.35
-c, --color COLOR	Colour (r,g,b or #RRGGBB)	#3399FF

Environment variables

Variable	Description	Default
RIPPLE_DURATION (s) / RIPPLE_DURATION_MS	Animation length	0.45s
RIPPLE_MAX_RADIUS	Final radius	120
RIPPLE_START_RADIUS	Initial radius	12
RIPPLE_LINE_WIDTH	Ring width	4
RIPPLE_START_ALPHA	Opacity	0.35
RIPPLE_RING_GAP	Ring spacing	6
RIPPLE_RING_COUNT	Number of rings	3
RIPPLE_COLOR	Colour	#3399FF
RIPPLE_SOCKET_PATH	Control socket path	$XDG_RUNTIME_DIR/hypr-ripple.sock

Set env vars before launching the daemon, e.g.

RIPPLE_RING_COUNT=5 RIPPLE_COLOR='#FF7733' ripple-daemon &

Troubleshooting

• Ripple doesn’t appear – ensure ripple-daemon is running and the socket path matches the trigger. The daemon logs Ripple daemon listening on … on start-up.
• Clicks stop working – confirm you used the bindn flag (non-consuming). Old binds that mix pass and exec will interfere with mouse actions.
• Multiple monitors – the overlay automatically spans every active monitor; no extra configuration required.

License

MIT. Build cool demos. Share the ripple. 🎉