Skip to main content

Hotkeys and Settings

Hotkeys offer users a quick and easy way to interact with their in-game overlay. While they are often used to show or hide your app, they also provide access to features without disrupting gameplay. Make sure users can easily manage hotkey settings from your app’s settings panel.

Hotkeys play an important role in your app and when configured correctly provide a good user experience. Important points to consider:

  • Hotkeys enhance accessibility and ease of use in-game. They make interacting with your app faster and more intuitive. Hotkeys become even more crucial in games where users can’t access a mouse cursor, such as FPS titles or games running in exclusive mode.
  • Configure hotkeys through the app’s settings panel. Hotkeys are set inside your app’s own settings panel (typically on the desktop view), not through the Overwolf client itself.
  • Remind users about active hotkeys for overlays or windows. If an overlay or secondary window doesn’t open automatically, it's helpful to notify users about the relevant hotkey through reminders or tips in your UI.
  • Avoid hotkey conflicts with other apps. Notify users which hotkeys are assigned and when they are changed. When possible, check for conflicts with hotkeys from other apps to prevent unintended behavior.
important

All app hotkeys removed once the extension is uninstalled.

Types of hotkeys​

There are four types of hotkeys used:

  • Toggle—allow users to quickly open or hide your app with a single keypress, without fully closing it. This is perfect for fast, seamless access during gameplay without disrupting their experience.
  • Custom—let users assign specific actions to keys—such as opening a specific window, triggering a feature, or interacting with part of the app. These hotkeys give users greater control over how they use your app, but they work only while the app is already running.
  • Hold—enable actions that happen only while the user is holding down a key (and stop when they release it). This is useful for temporary overlays or quick views. Its similar to how holding Tab in some games shows a map or scoreboard.
  • Global—allow users to access your app's functions across multiple games or globally outside of just one title. These are helpful for apps that work across different experiences or have background functionality users want to access anywhere.

Toggle​

Add a toggle switch (hotkey) to your app to show or hide the app without closing it. It can activate/launch your app even if the app is closed. You can also use this to launch your in-game app window.

info

If you are using a transparent background controller (window), a toggle hotkey will not work properly. Please use a custom hotkey.

Example:

 this.overlayApi.hotkeys.register(
      {
        name: 'show/hide',
        keyCode: 72, // h
        modifiers: {
          ctrl: true,
        },
      },
      (hotkey, state) => {
        // show/hide on press -> toggle behavior
        if (state == 'pressed') {
          this.handleShowHide('in-game-window');
        }
      },
    );

Custom hotkeys​

You can customize your app's window behavior by adding a custom hotkey to trigger an action. Custom hotkeys will only function when your app is already running (unlike Toggle hotkeys). Using a custom hotkey with the app closed will do nothing.

Hold hotkeys​

The hold hotkey functions while the configured hotkey is pressed down, and stops when its released. The functionality is similar to what you would find in some games.

Example:

      {
        name: 'show/hide',
        keyCode: 72, // h
        modifiers: {
          ctrl: true,
        },
      },
      (hotkey, state) => {
        // show on hold
        if (state == 'pressed') {
          this.showWindow();
        }

        // hide on release
        if (state == 'released') {
          this.hideWindow();
        }
      },

Hotkeys best practices​

Other recommended best practices for hotkeys include:

  • Provide a method of reassigning Hotkeys.
  • Provide a passthrough option so that the hotkey will not interfere with other keys in the game. For more information, see the passthrough property in IOverlayHotkey.

Reassign Hotkeys​

You should provide users a method to assign/reassign their hotkeys directly from within your app.

To provide users with this option, use:

Pass through​

You can set a hotkey as passthrough so that the hotkey will not interfere with other keys in the game.
The key combination will trigger your app hotkey and then will passthrough the game.

    this.overlayApi.hotkeys.register(
      {
        name: 'show/hide',
        keyCode: 72, // h
        modifiers: {
          ctrl: true,
        },
        passthrough: true,
      },
      (hotkey, state) => {
        // show/hide on press -> toggle behavior
        if (state == 'pressed') {
          this.handleShowHide('in-game-window');
        }
      },
    );