# How to Implement Keyboard Shortcuts in ImGui: A Complete Guide to ImGuiKeyChord

> Learn to implement keyboard shortcuts in ImGui using ImGuiKeyChord and the Shortcut API. This guide covers routing focus detection and modifier combinations for efficient UI development.

- Repository: [omar/imgui](https://github.com/ocornut/imgui)
- Tags: how-to-guide
- Published: 2026-07-23

---

**Dear ImGui provides a modern shortcut system using `ImGuiKeyChord` and the `ImGui::Shortcut()` API, which handles routing, focus detection, and modifier combinations automatically.**

The `ocornut/imgui` library offers a routing-aware approach to keyboard shortcuts that replaces legacy key checking with a declarative system. By leveraging the `ImGuiKeyChord` type introduced in recent versions, you can register shortcuts that respect window focus hierarchies and resolve conflicts automatically. This implementation centers around two primary functions defined in [`imgui.h`](https://github.com/ocornut/imgui/blob/main/imgui.h) (lines 255–267 and 1060–1092) and implemented in [`imgui.cpp`](https://github.com/ocornut/imgui/blob/main/imgui.cpp).

## Understanding the ImGuiKeyChord API

### What is ImGuiKeyChord?

An **`ImGuiKeyChord`** is an alias for `int` that stores a primary key combined with modifier flags. Rather than manually checking `io.KeyCtrl` and `IsKeyPressed()`, you combine keys with modifiers using bitwise OR operations.

The available modifier constants include:
- `ImGuiMod_Ctrl`
- `ImGuiMod_Shift`
- `ImGuiMod_Alt`
- `ImGuiMod_Super`

For example, `ImGuiMod_Ctrl | ImGuiKey_S` creates a chord representing Ctrl+S.

### Core Functions: Shortcut() and SetNextItemShortcut()

The shortcut system exposes two main entry points:

**`ImGui::Shortcut(key_chord, flags?)`** – Registers a routing request for the current context. Returns `true` if the shortcut is routed to the caller based on focus and priority rules.

**`ImGui::SetNextItemShortcut(key_chord, flags?)`** – Binds a shortcut to the next widget created (such as a button), causing activation when the chord is pressed.

These declarations appear in [`imgui.h`](https://github.com/ocornut/imgui/blob/main/imgui.h) around lines 1060–1092, while the routing logic resides in [`imgui.cpp`](https://github.com/ocornut/imgui/blob/main/imgui.cpp) near line 3641.

## Implementing Keyboard Shortcuts in ImGui: Practical Examples

### Global Shortcuts (Ctrl+S)

To implement a global save shortcut that triggers an action when pressed:

```cpp
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_S)) {
    SaveCurrentDocument();
}

```

This registers the chord with default routing, meaning it respects the current focus scope but can be claimed by the active window.

### Window-Scoped Shortcuts (Ctrl+F)

For shortcuts that should only activate when a specific window has focus, use the `ImGuiInputFlags_RouteFocused` flag:

```cpp
ImGui::Begin("Editor");
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_F, ImGuiInputFlags_RouteFocused)) {
    FindInDocument();
}
ImGui::End();

```

According to the implementation in [`imgui.cpp`](https://github.com/ocornut/imgui/blob/main/imgui.cpp), this restricts the shortcut to the currently focused window chain, preventing activation when other windows are active.

### Button Activation Shortcuts (Ctrl+N)

To make a button clickable via keyboard shortcut without manually checking keys:

```cpp
ImGui::SetNextItemShortcut(ImGuiMod_Ctrl | ImGuiKey_N);
if (ImGui::Button("New")) {
    CreateNewDocument();
}

```

The `SetNextItemShortcut` function attaches the chord to the subsequent widget. When Ctrl+N is pressed, the button activates as if clicked.

### Repeating Shortcuts (Ctrl+Z)

For actions that should repeat while the key is held (such as undo or scrolling), combine the chord with `ImGuiInputFlags_Repeat`:

```cpp
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_Z, ImGuiInputFlags_Repeat)) {
    UndoLastAction();
}

```

This flag leverages the internal repeat timing system, firing the shortcut at regular intervals while the chord remains pressed.

## Shortcut Routing and Input Flags

### Routing Priority System

The routing system, implemented in [`imgui.cpp`](https://github.com/ocornut/imgui/blob/main/imgui.cpp) around line 3641, resolves shortcut conflicts by giving priority to the most specific owner. A focused child window overrides its parent, and active items take precedence over background windows. This architecture prevents shortcut leakage between unrelated UI sections.

The routing data structures (`ImGuiKeyRoutingData`) and helper functions (`SetShortcutRouting`, `TestShortcutRouting`) are defined in [`imgui_internal.h`](https://github.com/ocornut/imgui/blob/main/imgui_internal.h), exposing the mechanism that powers the public API.

### Available Input Flags

Control shortcut behavior using **`ImGuiInputFlags`**:

- **`ImGuiInputFlags_RouteFocused`** – Only trigger if the calling window is in the focus stack
- **`ImGuiInputFlags_RouteGlobal`** – High-priority global shortcut that bypasses normal focus checks
- **`ImGuiInputFlags_Repeat`** – Enable key repeat behavior for the shortcut

These flags combine to create complex input hierarchies without manual state tracking.

## Shortcut() vs IsKeyChordPressed()

While `IsKeyChordPressed()` reports raw key state without context, **`Shortcut()`** is the recommended approach for production code. The key differences include:

- **Routing awareness**: `Shortcut()` checks focus ownership and resolves conflicts through the routing system
- **Registration**: `Shortcut()` submits a routing request that participates in the frame's input processing
- **Future compatibility**: The routing-based API is actively maintained and supports upcoming features like chord sequences

Use `IsKeyChordPressed()` only for debugging or when bypassing the routing system is explicitly required.

## Summary

- **`ImGuiKeyChord`** combines keys with modifiers (`ImGuiMod_Ctrl | ImGuiKey_S`) for type-safe shortcut definitions
- **`ImGui::Shortcut()`** provides routing-aware shortcut detection with automatic focus handling
- **`ImGui::SetNextItemShortcut()`** binds chords directly to widgets for activation
- **Routing flags** (`RouteFocused`, `RouteGlobal`) control scope and priority without manual focus checks
- **Implementation files**: Declarations in [`imgui.h`](https://github.com/ocornut/imgui/blob/main/imgui.h) (lines 255, 1060–1092), logic in [`imgui.cpp`](https://github.com/ocornut/imgui/blob/main/imgui.cpp) (line 3641), internals in [`imgui_internal.h`](https://github.com/ocornut/imgui/blob/main/imgui_internal.h)
- **Demo code**: Reference [`imgui_demo.cpp`](https://github.com/ocornut/imgui/blob/main/imgui_demo.cpp) for working examples of complex shortcut configurations

## Frequently Asked Questions

### How do I detect Ctrl+S in ImGui?

Use `ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_S)` within your window code or global scope. This function returns `true` when the chord is pressed and routed to your context, unlike manual key checking which ignores focus state.

### What is the difference between Shortcut() and IsKeyChordPressed()?

`Shortcut()` registers the request with ImGui's routing system, checks focus ownership, and resolves conflicts automatically. `IsKeyChordPressed()` only reports whether keys are physically pressed, requiring manual focus validation and offering no conflict resolution.

### How do I make a shortcut work only when a specific window is focused?

Pass `ImGuiInputFlags_RouteFocused` as the second argument to `ImGui::Shortcut()`. When called between `ImGui::Begin()` and `ImGui::End()`, this flag restricts activation to when that specific window or its children have focus.

### Where are the keyboard shortcut functions defined in the ImGui source?

The type `ImGuiKeyChord` and function declarations appear in [`imgui.h`](https://github.com/ocornut/imgui/blob/main/imgui.h) around lines 255 and 1060–1092. The routing implementation and `Shortcut()` logic reside in [`imgui.cpp`](https://github.com/ocornut/imgui/blob/main/imgui.cpp) near line 3641. Internal routing structures are located in [`imgui_internal.h`](https://github.com/ocornut/imgui/blob/main/imgui_internal.h).