Files

T

felixzsh 7ab4d2f18d Linger on screen after release, keyviz-style

Previously the chips cleared the instant the keys were released, so the
120ms hide delay was invisible. Keep the last combo rendered for the
whole linger window and only clear it when the timer fires, so a quick
tap stays readable (keyviz keeps keys for lingerDurationMs, 5s by
default). Default 1000ms, tunable via lingerMs.

2026-08-11 10:52:54 -05:00

3.8 KiB

Raw Blame History

Omarchy Key Visualizer

A tiny Omarchy plugin that shows the keys you press on screen. No keycap images, no animations — just the characters and combinations, rendered with the shell's own styles, appearing while a key is held and disappearing the moment it's released.

Built for keybinding tutorials and screencasts: Omarchy is a keybinding-heavy desktop, so a combo like Super + Shift + G shows up as three small chips at the bottom of the screen.

How it works

Piece	Where it runs	What it does
`key-visualizer.lua`	Hyprland Lua config (inside the compositor)	Listens to `input.keyboard.key`, tracks the pressed combo, writes it to `$XDG_RUNTIME_DIR/omarchy-key-visualizer.json`
`KeyVisualizer.qml`	Quickshell `omarchy-shell` (keep-loaded panel)	Watches the state file and renders the chips

No background daemons, no special permissions, no extra packages: the compositor is already the source of truth for keys, and the shell is already running.

Install

Validate the folder first (optional but handy for plugin authors):

omarchy plugin validate ./omarchy-keycaster

Then add it — a local path works as well as a git URL (plugin add clones with git, and git clone accepts local paths):

omarchy plugin add /path/to/omarchy-keycaster --enable
# or once published:
# omarchy plugin add https://github.com/YOU/omarchy-keycaster --enable

--enable enables it right away; without it, enable later with omarchy plugin enable felixzsh.key-visualizer. If you added from a local path, omarchy plugin update felixzsh.key-visualizer pulls your local changes into the installed copy.

Then load the capture script into Hyprland's Lua config. Add this line at the bottom of ~/.config/hypr/hyprland.lua:

dofile(os.getenv("HOME") .. "/.config/omarchy/plugins/felixzsh.key-visualizer/key-visualizer.lua")

Reload Hyprland:

hyprctl reload

The panel starts with the shell, so it works after the next login too.

Requirements

Hyprland with Lua config support (0.56+), as shipped by Omarchy.
The plugin enabled in the shell (done above).

Behavior

Typing — shows just the character: g, G, !, 5.
Modifier combos — shows every modifier plus the key: Super Shift G, Ctrl C, Super Enter.
Non-printing keys — labeled: Esc, Tab, F1, arrows, Space.
Modifiers that produce the shifted character (Shift with a letter) are folded into the character itself: Shift + 1 shows !.
Key repeat is ignored; a held key shows once.
After the last key is released the combo lingers briefly (1s by default, keyviz-style "Duration") and then vanishes in one frame — no fade.

Customize

Everything lives in the plugin directory (~/.config/omarchy/plugins/felixzsh.key-visualizer/); saved changes reload automatically.

Want to change...	Edit
How long a released combo lingers	`lingerMs` in `KeyVisualizer.qml` (default `1000`; keyviz defaults to `5000`)
Chip font / padding	`chipFont`, `chipPadX/Y` in `KeyVisualizer.qml`
Key labels or layout mapping	`KEYS` / `CHARS` / `SHIFTED` tables in `key-visualizer.lua`

The key tables use US layout keycode mapping. Letters and digits match most layouts; on other layouts, symbol keys (;, [, ñ, …) may show the US glyph or fall back to the key name. Dead keys and compose sequences are not expanded.

Status

omarchy-shell key-visualizer ping — health check.

Roadmap

Layout-aware keysyms via xkbcommon instead of the static US table.
Mouse button display.
A pause toggle for presentations.

License

MIT

3.8 KiB Raw Blame History