Keybindings

YASB supports global keyboard shortcuts (hotkeys) to trigger widget actions. Keybindings are configured per-widget in the widget's options section. This feature uses the native Windows RegisterHotKey API and requires no third-party dependencies.

Overview

Per-widget instance: Keybindings are tied to the specific widget name in your config (e.g., clock vs clock_2)
Multiple keybindings: A single widget can have multiple keybindings for different actions
Screen-aware: Hotkeys trigger the widget on the currently focused screen
Zero overhead: If no keybindings are defined, no hotkey listener is started
No auto-repeat: Holding a hotkey fires only once (uses MOD_NOREPEAT)

Configuration

Add a keybindings list to any widget's options. Each keybinding requires:

keys: The key combination (e.g., "win+c", "ctrl+shift+f1")
action: The callback action to trigger (e.g., "toggle_calendar", "toggle_label")
screen (optional): "active", "cursor", or "primary" to specify which screen to target if multiple are present (defaults to "active" — the focused window's screen)

Basic Example

clock:
  type: "yasb.clock.ClockWidget"
  options:
    label: "{%H:%M}"
    keybindings:

      - keys: "win+c"
        action: "toggle_calendar"

      - keys: "ctrl+shift+t"
        action: "toggle_label"

Multiple Widgets Example

clock:
  type: "yasb.clock.ClockWidget"
  options:
    keybindings:

      - keys: "win+c"
        action: "toggle_calendar"
        screen: "cursor"

volume:
  type: "yasb.volume.VolumeWidget"
  options:
    keybindings:

      - keys: "win+v"
        action: "toggle_menu"

Supported Keys

Modifier Keys

Key Name	Description
`win`, `windows`, `super`, `meta`	Windows key
`alt`	Alt key
`ctrl`, `control`	Control key
`shift`	Shift key

Note: RegisterHotKey does not distinguish between left and right modifier keys.

Function Keys

Key Name	Description
`f1` - `f24`	Function keys F1 through F24

Letter and Number Keys

Key Name	Description
`a` - `z`	Letter keys (case-insensitive)
`0` - `9`	Number keys

Special Keys

Key Name	Aliases	Description
`space`		Spacebar
`tab`		Tab key
`enter`, `return`		Enter/Return key
`esc`, `escape`		Escape key
`backspace`		Backspace key
`delete`, `del`		Delete key
`insert`, `ins`		Insert key
`home`		Home key
`end`		End key
`pageup`, `pgup`		Page Up key
`pagedown`, `pgdn`		Page Down key
`pause`		Pause key
`capslock`, `caps`		Caps Lock key
`numlock`		Num Lock key
`scrolllock`		Scroll Lock key
`printscreen`, `prtsc`		Print Screen key

Arrow Keys

Key Name	Description
`left`	Left arrow
`up`	Up arrow
`right`	Right arrow
`down`	Down arrow

Numpad Keys

Key Name	Description
`numpad0` - `numpad9`	Numpad number keys
`multiply`	Numpad *
`add`	Numpad +
`subtract`	Numpad -
`decimal`	Numpad .
`divide`	Numpad /

Punctuation and Symbol Keys

Key Name	Description
`semicolon`	; key
`equal`, `equals`	= key
`comma`	, key
`minus`	- key
`period`	. key
`slash`	/ key
`backquote`, `grave`	` key
`bracketleft`	[ key
`bracketright`	] key
`backslash`	\ key
`quote`	' key

Limitations

No Multi-Key Combos

YASB only supports modifier + single key combinations. You cannot bind multiple non-modifier keys together:

Configuration	Valid
`"alt+a"`	Yes
`"ctrl+shift+f1"`	Yes
`"a+b"`	No - two non-modifier keys
`"f13+h"`	No - two non-modifier keys

Windows Key Limitations

Windows Explorer pre-registers many Win+key shortcuts (e.g., Win+S, Win+W, Win+Shift+S). RegisterHotKey cannot override these - the registration will silently fail. Use Alt, Ctrl, or Ctrl+Shift based combinations instead for reliable hotkeys.

Modifier-Only Hotkeys Not Supported

You cannot use a modifier key alone as a hotkey:

Configuration	Valid
`"ctrl"`	No - no main key
`"alt+shift"`	No - no main key
`"win+a"`	Yes

Extra Modifiers Don't Block

Unlike a low-level hook, RegisterHotKey does not reject extra modifiers. If you register alt+x, pressing ctrl+alt+x will also trigger it. Keep this in mind when choosing key combinations.

Available Actions

Each widget has its own set of available callback actions. Common actions include:

Action	Description
`toggle_label`	Toggle between primary and alternate label
`toggle_menu`	Show/hide the widget's menu
`update_label`	Force refresh the widget label
`do_nothing`	No action (useful for disabling)

Refer to individual widget documentation for widget-specific actions. For example, the Clock widget supports:

toggle_calendar - Show/hide calendar popup
toggle_label - Toggle between label formats
next_timezone - Cycle to next timezone
context_menu - Show context menu

Screen Targeting

When a hotkey is triggered, YASB determines which screen's widget should respond. You can control this per-keybinding with the screen option:

Value	Behavior
`"active"` (default)	Targets the screen containing the currently focused window. Falls back to primary if no window is focused.
`"cursor"`	Targets the screen where the mouse cursor is currently located.
`"primary"`	Always targets the primary screen.

This means pressing win+c will toggle the calendar on the monitor where you're currently working (by default), or you can override this to follow the mouse cursor or always use the primary screen.

Conflict Handling

If the same key combination is assigned to multiple widgets, YASB will:

Log a warning message indicating the conflict
Use the last defined keybinding (later widgets override earlier ones)

WARNING: Hotkey conflict: 'win+c' is already assigned to 'yasb.clock.ClockWidget',
overriding with 'yasb.volume.VolumeWidget'

If another application has already registered the same hotkey with Windows, YASB will log a warning and that hotkey will not work.

To avoid conflicts, use unique key combinations for each widget action.

Troubleshooting

Hotkey Not Working

Check the logs: Enable debug logging to see if the hotkey was registered successfully
Verify key names: Ensure you're using supported key names from the tables above
Check for conflicts: Another application may have registered the same combination - RegisterHotKey is first-come-first-served
Reserved Windows combos: Win+L (lock screen) and Ctrl+Alt+Delete cannot be overridden

Hotkey Registered but Not Responding

If the log shows the hotkey was registered successfully but it doesn't trigger:

Ensure the widget has the corresponding action callback
Check that the widget's keybindings config matches the expected action name