Allow unbinding a key by description or from a submap

[uhs-robert]

Problem

The hl.unbind command unbinds every instance of the key specified from every context that it is used in (i.e. from the top level and within every submap).

• There is no way to limit the scope of unbind to a specific submap context or to target a specific instance of the key by description.
• This creates an issue where users may want to unbind a key from a specific scope but are unable to do so.

This additional functionality would be helpful to allow users to target a specific context where a key is used, or a specific instance of a key, when unbinding. This would be especially useful for submaps where users may want to dynamically generate/delete keybinds during runtime (that's my usecase) to enable more sophisticated dynamic keybind generation via Lua without accidentally/unintentionally deleting the same key that is used elsewhere.

Expected Result

Allow hl.unbind to accept opts = {} for filtering the scope of the unbind to target a key within a specific submaps or by description.

Or, if simpler, allow unbinding via a saved variable like how disabling a workspace rule works.

[wabarTM]

but submaps already override binds unless you use submap_universal = true in bind flags

[uhs-robert]

Right, but I’m not asking about bind precedence or whether submaps override top-level binds.

The issue is specifically with removal. hl.unbind will remove every bind matching that key, rather than allowing removal of only the bind in a specific submap or the bind with a specific description.

So the problem is not "how do I make a submap bind win?" The problem is "how do I delete only this generated bind without deleting other binds that use the same key elsewhere?"

---

For example:

• H is bound in the top-level to do some action.
• H is bound in Submap "Windows" to focus the left window.
• Elsewhere, a Lua script dynamically creates a temporary submap "Marks" where H performs a generated action within that submap with a generated description.
  • During runtime, the Lua script later needs to delete only that generated submap bind from "Marks" to re-register it to another dynamic action and update the description.

However, currently, hl.unbind("H") will remove all H binds from the top-level and from every submap. This completely unbinds H across all contexts (top-level, "Windows", "Marks", etc:) when the intended recipient was meant to only be "Marks".

[tekstryder]

One of the most clearly articulated problem statements I've ever seen here.

A scoping issue I'll never encounter, but feel compelled to upvote.

[Dregu]

Or, if simpler, allow unbinding via a saved variable

Well you'll be happy to know that this is how it already works. A ton of advanced features are only documented in the LSP definitions in /usr/share/hypr/stubs/hl.meta.lua...

foo = hl.bind('X', ...)
foo:unbind()

[uhs-robert]

Ah! Thank you, this solves my immediate use case.

I tried looking for this in the public docs but did not find it there. Thanks for pointing to me to the stubs. I checked them earlier, but I missed that hl.bind() returns an object with :unbind() on self.

I would normally close this as resolved since my direct use case is covered, but I think there may still be two useful follow-ups here:

1. Wiki Update

I can take a look at doing this myself.

The public docs make hl.unbind() look like the only available unbind API. Meanwhile, the safer handle-based bind:unbind() option is only discoverable through the LSP stubs.

2. Selector-based unbind API

The handle-based approach works and is consistent with how other Hyprland Lua objects work (like Window Rules).

That said, for dynamic submaps/menus, users currently need to maintain their own lookup table of bind handles if they want to clean up generated binds later. That works when creation and cleanup happen in the same Lua context.

However, if cleanup is triggered from a different script/module/context, that script does not naturally have access to the original bind handles unless the user exposes them through some shared/global registry. At that point, every dynamic keybind system has to create and manage its own registry just to perform targeted cleanup.

A selector-based unbind API could avoid that by allowing cleanup based on bind metadata that Hyprland already knows about, for example:

hl.unbind("J", { submap = "my_dynamic_menu" })
hl.unbind("J", { description = "jump to item 1" })
hl.unbind({ submap = "my_dynamic_menu" })

So the existing handle-based approach solves precise unbinding when the caller has access to the original bind object, but a selector-based API may still improve ergonomics for generated/dynamic bind systems and cross-module cleanup.

[uhs-robert]

Follow-up

I tested this more, and bind:unbind() does not appear to solve the scoped-unbind case after all.

Unless I am missing something, calling :unbind() on the returned bind object still removes matching binds globally by key. It does not remove only that specific bind instance.

So this:

local foo = hl.bind("J", ...)
local bar = hl.bind("J", ...)

bar:unbind()

Appears to remove all matching J binds including foo and not just bar.

Although the object syntax exists, the behavior still seems the same as the key based hl.unbind API command. The original issue remains: there does not appear to be a way to remove one specific generated bind without also removing unrelated binds that share the same key.

[Dregu]

Wow that seems like a weird oversight, I guess the underlying data structure still treats the literal key as a unique key and it needs an overhaul...

[HighFunctioningSociopathSH]

Any updates on this? I really need this feature. I am creating submaps dynamically based on other events, and the binds inside them are multiplying every time. Normally, clearing the old bind before creating them again would instantly fix the issue, except the problem is that unbind clears the key from all submaps

[HighFunctioningSociopathSH]

I just checked, for some reason bind:set_enabled works by only disabling that specific bind but bind:remove and bind:unbind will unregister the binding in all submaps