> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overlayed.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Keybinds

> Keybinds allow your users to interact with your overlay via their keyboard.

## Defining Keybinds

Keybinds are defined programmatically within the overlayed setup. This means runtime keybinds are not supported.

```typescript theme={null}
export const overlay = overlayed({
	keybinds: {
		showMainWindow: {
			keys: ["AltLeft", "KeyX"],
			mode: "toggle",
		},
		showScoreboardWindow: {
			keys: ["Backquote"],
			mode: "hold",
		},
	},
});
```

Let's break down the above config:

* `showMainWindow` or `showScoreboardWindow`
  * These are names that you define for the keybind.
  * They'll be used later on to listen to the keybind
* `keys`
  * An array of [KeyboardEvent#code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code)
  * Whatever you configure will be the default value
  * [Here](https://www.toptal.com/developers/keycode) is a good tool to easily find the codes for a given keybind
* `mode`
  * `"toggle"` will trigger the callback when the key is toggled on and off
  * `"hold"` will trigger the callback when the key is held down
  * This can be updated at runtime

<Info>We currently offer no way to migrate keybind names to new ones.</Info>

## Listening to Keybinds

Once a keybind is configured, it's trivial to listen to it anywhere in your overlay:

```typescript theme={null}
overlay.keybinds.showMainWindow.on("toggle", () => {
	myWindow.toggleVisibility();
});

overlay.keybinds.showMainWindow.on("up", () => {
	myWindow.hide();
});

overlay.keybinds.showMainWindow.on("down", () => {
	myWindow.show();
});
```

If you plan on allowing users to configure the `mode` of a keybind, you'll want to handle all three events.

## Updating Keybinds

It's highly recommended to create a UI to allow users to update the app's keybinds for complete customization.

You can accomplish this easily:

```typescript theme={null}
// Update a single keybind
overlay.keybinds.updateKeybind("showMainWindow", {
	// ...
});

// Bulk update,
overlay.keybinds.updateKeybinds({
	// ...
});
```

This will save their new settings to the file system automatically, so there's nothing else for you to worry about.

### Pausing Keybind Listening

When implementing your UI to allow users to record new keybinds, it's critical to call `pauseKeybindListening` and
`resumeKeybindListening` functions before and after the user records the keybind.

This will prevent them from triggering an existing keybind while recording a new one. This is only a concern for in-game
windows, so if you don't allow users to change keybinds via an in-game window, you can skip this section.

## Rejecting Keybinds

Sometimes you may want to block a keybind on a window, for example blocking opening of a custom scoreboard if the user
isn't in a match.

You can accomplish this by returning a string from the listener, which represents a reason for blocking the keybind.

```typescript theme={null}
overlay.keybinds.showMainWindow.on("toggle", () => {
	if (!siegeState.match) {
		return "Not in a match";
	}

	myWindow.toggleVisibility();
});

overlay.keybinds.showMainWindow.on("down", () => {
	if (!siegeState.match) {
		return "Not in a match";
	}

	myWindow.show();
});
```

Currently the returned reason string is just used for logging purposes, but can also serve as self-documenting code.

## Best Practices

* Always pause keybind listening during keybind recording.
* Validate keybind conflicts when users update keybinds.