Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.

hotkey PkgGoDev hotkey

cross platform hotkey package in Go

import ""


  • Cross platform supports: macOS, Linux (X11), and Windows
  • Global hotkey registration without focus on a window

API Usage

Package hotkey provides the basic facility to register a system-level global hotkey shortcut so that an application can be notified if a user triggers the desired hotkey. A hotkey must be a combination of modifiers and a single key.

package main

import (


func main() { mainthread.Init(fn) } // Not necessary when use in Fyne, Ebiten or Gio.
func fn() {
	hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}, hotkey.KeyS)
	err := hk.Register()
	if err != nil {
		log.Fatalf("hotkey: failed to register hotkey: %v", err)

	log.Printf("hotkey: %v is registered\n", hk)
	log.Printf("hotkey: %v is down\n", hk)
	log.Printf("hotkey: %v is up\n", hk)
	log.Printf("hotkey: %v is unregistered\n", hk)

Note platform specific details:

  • On macOS, due to the OS restriction (other platforms does not have this restriction), hotkey events must be handled on the "main thread". Therefore, in order to use this package properly, one must start an OS main event loop on the main thread, For self-contained applications, using is possible. It is uncessary or applications based on other GUI frameworks, such as fyne, ebiten, or Gio. See the "./examples" folder for more examples.
  • On Linux (X11), when AutoRepeat is enabled in the X server, the Keyup is triggered automatically and continuously as Keydown continues.
  • On Linux (X11), some keys may be mapped to multiple Mod keys. To correctly register the key combination, one must use the correct underlying keycode combination. For example, a regular Ctrl+Alt+S might be registered as: Ctrl+Mod2+Mod4+S.
  • If this package did not include a desired key, one can always provide the keycode to the API. For example, if a key code is 0x15, then the corresponding key is hotkey.Key(0x15).


Description Folder
A minimum example minimum
Register multiple hotkeys multiple
A example to use in GLFW glfw
A example to use in Fyne fyne
A example to use in Ebiten ebiten
A example to use in Gio gio

Who is using this package?

The main purpose of building this package is to support the midgard project.

To know more projects, check our wiki page.


MIT | © 2021 The Initiative Authors, written by Changkun Ou.