How to Implement Keyboard Shortcuts in ImGui Using ImGuiKeyChord

ImGui::Shortcut() accepts an ImGuiKeyChord (a key plus modifier flags) and returns true when the shortcut is activated, handling focus routing and conflicts automatically.

Dear ImGui provides a modern, routing-aware shortcut system built around the ImGuiKeyChord type. Defined in imgui.h (lines 255‑267) and implemented in imgui.cpp, this API replaces legacy key polling with a declarative approach that respects window focus and input ownership. Whether you need global application shortcuts or context-sensitive editor commands, the combination of ImGuiKeyChord and ImGui::Shortcut() offers a robust, future-proof solution.

Understanding ImGuiKeyChord and Modifier Flags

An ImGuiKeyChord is fundamentally an alias for int that stores a key value combined with modifier bit flags. According to the source definitions in imgui.h, you construct chords by bitwise-ORing an ImGuiKey with one or more ImGuiMod_ flags.

Available modifier flags include:

• ImGuiMod_Ctrl
• ImGuiMod_Shift
• ImGuiMod_Alt
• ImGuiMod_Super

For example, ImGuiMod_Ctrl | ImGuiKey_S creates a chord representing Ctrl+S. This composite value is what you pass to the shortcut functions.

Core Shortcut Functions

The shortcut system centers on two primary functions declared in imgui.h (lines 1060‑1092):

ImGui::Shortcut(ImGuiKeyChord key_chord, ImGuiInputFlags flags=0)

This function registers a shortcut request for the current frame. It returns true only if the chord is pressed and the routing system determines this context has priority. The implementation in imgui.cpp (around line 3641) handles the complexity of conflict resolution and focus checking.

ImGui::SetNextItemShortcut(ImGuiKeyChord key_chord, ImGuiInputFlags flags=0)

This assigns a shortcut to the next widget that will be created (for example, a button). When the chord fires, the widget activates as if clicked.

Routing Behavior and Input Flags

Unlike raw key checking, ImGui::Shortcut() implements a sophisticated routing system defined in imgui_internal.h and implemented in imgui.cpp. The optional ImGuiInputFlags parameter controls how the shortcut resolves:

• ImGuiInputFlags_RouteFocused: The shortcut only fires when the current window or item has focus. Child windows override parent windows in the routing hierarchy.
• ImGuiInputFlags_RouteGlobal: The shortcut fires regardless of focus, acting as a global hotkey.
• ImGuiInputFlags_Repeat: The shortcut triggers repeatedly while the key chord is held down, respecting the user's key repeat settings.

Complete Implementation Examples

The following patterns demonstrate practical usage patterns found in imgui_demo.cpp:

// Example 1: Simple global shortcut (Ctrl+S) to trigger an action
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_S)) {
    SaveCurrentDocument();
}

// Example 2: Shortcut that repeats while the key is held (Ctrl+Z for undo)
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_Z, ImGuiInputFlags_Repeat)) {
    UndoLastAction();
}

// Example 3: Assign a shortcut to a button (Ctrl+N for "New")
ImGui::SetNextItemShortcut(ImGuiMod_Ctrl | ImGuiKey_N);
if (ImGui::Button("New")) {
    CreateNewDocument();
}

// Example 4: Scoped shortcut that only works when a specific window is focused
ImGui::Begin("Editor");
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_F, ImGuiInputFlags_RouteFocused)) {
    FindInDocument();
}
ImGui::End();

// Example 5: Explicit global routing for application-level commands
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_Q, ImGuiInputFlags_RouteGlobal)) {
    QuitApplication();
}

Why Prefer Shortcut() Over IsKeyChordPressed()

While IsKeyChordPressed() merely reports raw key state without context, ImGui::Shortcut() provides several architectural advantages as implemented in the Dear ImGui source:

• Automatic focus checking: Respects the active window hierarchy
• Conflict resolution: Handles overlapping shortcuts through the routing system outlined in imgui_internal.h
• Integration: Works seamlessly with Dear ImGui's input ownership and shortcut routing tables
• Repeat support: Native handling of key repeat behavior through ImGuiInputFlags_Repeat

For these reasons, Shortcut() is the recommended API for all new ImGui keyboard shortcuts.

Summary

• ImGuiKeyChord combines ImGuiKey values with ImGuiMod_ flags using bitwise OR (e.g., ImGuiMod_Ctrl | ImGuiKey_S)
• Use ImGui::Shortcut() declared in imgui.h to register shortcuts with automatic routing and conflict resolution
• Use ImGui::SetNextItemShortcut() to bind shortcuts to specific widgets before creating them
• Control scope with ImGuiInputFlags_RouteFocused (window-specific) or ImGuiInputFlags_RouteGlobal (application-wide)
• Enable key repeat with ImGuiInputFlags_Repeat for actions like undo/redo
• Reference the implementation details in imgui.cpp (around line 3641) and examples in imgui_demo.cpp

Frequently Asked Questions

What is the difference between ImGuiKeyChord and ImGuiKey?

An ImGuiKey represents a single physical or logical key (such as ImGuiKey_S or ImGuiKey_LeftShift), while an ImGuiKeyChord combines a key with modifier flags. In the source code (imgui.h line 255), ImGuiKeyChord is defined as an int that can hold both the key value and modifier bits (ImGuiMod_Ctrl, ImGuiMod_Shift, etc.) in a single composite value.

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

Pass the ImGuiInputFlags_RouteFocused flag to ImGui::Shortcut(). When used inside a window block (between ImGui::Begin() and ImGui::End()), the shortcut will only activate if that window has focus. The routing system in imgui.cpp automatically prioritizes focused children over parent windows.

Can I use Shortcut() for global hotkeys that work anywhere in my application?

Yes. Pass the ImGuiInputFlags_RouteGlobal flag to ImGui::Shortcut(). According to the implementation in imgui.cpp, this bypasses the focused-window check, allowing the shortcut to trigger regardless of which window is active. Place these calls in your main update loop rather than inside specific window blocks.

Where can I find more examples of ImGui keyboard shortcuts?

The imgui_demo.cpp file in the ocornut/imgui repository contains comprehensive demonstrations of the shortcut system. Search for calls to Shortcut( to find interactive examples. Additionally, imgui_internal.h exposes advanced routing internals such as ImGuiKeyRoutingData and SetShortcutRouting for developers needing custom shortcut behaviors.

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