# Keybind

> Keybind is a key binding button like the Controls screen's - click it, press a key or mouse button, or Escape to unbind - storing a version-independent Key.

URL: https://xichil.dev/docs/xis-mvui/v1/widgets/keybind/ · Updated: 2026-11-06 · Applies to: Fabric, Quilt, Legacy Fabric, Forge, NeoForge, MC 1.7.10 - 26.3

A key binding button, as on vanilla's Controls screen: "label: key". Clicking it makes the button wait for the
next key or mouse button; the next press is bound, and Escape unbinds. The key is a
[Key](https://xichil.dev/javadoc/xis-mvui/v1/dev/xichil/mvui/Key.html), the same on every Minecraft version.

```java
Keybind.builder("zoomKey")
        .label(Text.translatable("mymod.zoomKey", "Zoom"))
        .value(() -> config.zoomKey)          // a Key; null shows as unbound
        .onChange(key -> config.zoomKey = key)
        .build();
```

## Builder

| Method | Required | Default | Notes |
| --- | --- | --- | --- |
| `label(Supplier<Text>)` / `label(Text)` | yes | | the text before ": key" |
| `value(Supplier<Key>)` | yes | | your current key; `null` or `Key.UNBOUND` for none |
| `onChange(Consumer<Key>)` | yes | | stores the newly bound key; gets `Key.UNBOUND` when the player pressed Escape |
| `allowMouse(boolean)` | no | `true` | whether mouse buttons can be bound; if `false`, a click while waiting just stops waiting |
| `enabled`, `tooltip`, `visible` | no | | [options every widget has](https://xichil.dev/docs/xis-mvui/v1/widgets/index.md#options-every-widget-has) |

## Methods

| Method | Does |
| --- | --- |
| `key()` | your current key; `Key.UNBOUND` if your supplier returns `null` |
| `set(Key)` | binds a key, as given, and calls `onChange`. Use it for a Reset button: `zoom.set(Key.keyboard(90))`. |

## Behaviour

- The widget only **edits** a key. It doesn't register a vanilla key mapping or listen for the key in game; your
  mod checks it in its own input handler ([Key bindings](https://xichil.dev/docs/xis-mvui/v1/guides/keybinds/index.md#check-the-key-in-game)).
- There are no modifier combinations (Ctrl + key).
- The button shows the key's name the way vanilla does: translated, following the keyboard layout.
- Store keys as text with `key.name()` and read them back with `Key.fromName(text)`.
- **Footer:** no.

## Test it

```java
host.pressKey("zoomKey", Key.keyboard(82));     // binds R
host.pressKey("zoomKey", Key.ESCAPE);           // unbinds
```

Rendered as `[keybind zoomKey] Zoom: R`, or `Zoom: Not Bound`.

## See also

- Javadoc: [Keybind](https://xichil.dev/javadoc/xis-mvui/v1/dev/xichil/mvui/Keybind.html), [Key](https://xichil.dev/javadoc/xis-mvui/v1/dev/xichil/mvui/Key.html)
- [Key bindings](https://xichil.dev/docs/xis-mvui/v1/guides/keybinds/index.md)