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

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 (lines 255–267 and 1060–1092) and implemented in 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 around lines 1060–1092, while the routing logic resides in 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:

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:

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

According to the implementation in 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:

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:

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 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, 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 (lines 255, 1060–1092), logic in imgui.cpp (line 3641), internals in imgui_internal.h
• Demo code: Reference 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 around lines 255 and 1060–1092. The routing implementation and Shortcut() logic reside in imgui.cpp near line 3641. Internal routing structures are located in imgui_internal.h.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}